GitHub things - mrhelmus/natdb GitHub Wiki
Helpful GitHub commands & links when writing a new download function for NaTDB
There are two main ways that GitHub allows for collaborating: command line git and GitHub Desktop. Learning command-line git is recommended for those who wish to implement a version control system for research, etc. However, for a first-time and occasional user of GitHub who works on a Mac or PC we recommend GitHub Desktop. You should read through everything below regardless of what you decide to use, and also be sure to have a GitHub account before starting. If you are completely unfamiliar with GitHub then watch this informercial.
Remember: when in doubt, ask the Google machine, then ask a person
The Basics of command-line git
-
From Will's master repository, click the "fork" button in the upper right hand of the screen to create your own fork of NaTDB
-
Cloning your new repository is easy!
git clone https://github.com/yourUserName/natdb.git
-
Once you've cloned the NaTDB repository to your computer, you'll need to be frequently committing and pushing your edits:
git commit -am "message about commit" git push
-
You can also use
git status
to see what needs to be committed or pushed. -
Other useful commands include:
git add filename
Merging Repositories
- When you're ready to merge from the master repository, follow the instructions on merging an upstream repository into your fork
- This page from GitHub on collaborating issues and pull requests has a lot of information to wade through, but can be very helpful with learning how to merge and such.
The Basics of GitHub Desktop
- First, install GitHub Desktop
- Then go online to Will's master repository, click the "fork" button in the upper right hand of the screen to create your own fork of NaTDB. Make sure you are logged in to GitHub when you do this.
- Now you need to clone (i.e., copy) your forked version of NaTDB to your computer. In GitHub Desktop Go to File -> Clone repository. Under the GitHub.com heading you should see
yourUserName\natdb
. This is your forked repository of NaTDB. Click on the repository, decide what folder you want to save the local copy (the default directory is..\GitHub\natdb
), and then click the Clone button. - Now all of the R code for NaTDB is locally stored on your computer.
- The R code that contains the download functions is the file
downloads.R
in the folder R. You will put your new download function in this file.
Commit, Push, Pull
- Commit: You commit a change to prepare for uploading (i.e., pushing) the edit file online. Once you make and save edits to
downloads.R
in your R editor (e.g., RStudio), then GitHub Desktop will automatically show the edits that you made. You need to commit these edits. In the bottom left hand of the GitHub Desktop window you will see the commit dialogue box where you summarize and describe your edits. The summary is just a title for the edits you want to commit, (e.g., "fixed error in read.csv"). The description is what you write to better describe what you edited. - Push: Push your edited and committed R file to your forked repository online. Push means that your local copy is uploaded to GitHub putting the relevant edits into your Origin (i.e., Origin is what a forked repository is called that is stored online). As you make edits to
downloads.R
you will want to frequently commit and push your edits back to your Origin. Doing this makes sure that you do not lose any of your changes. - Pull Request: Finally, when you are done with all of your edits and your new download function works, you make a Pull request to notify Will that you have a download function that you want him to include in NaTDB. You do this online. Go to your Orign's GitHub page online and click on the button New pull request. Then make sure that the changes you made are there, and click the green button marked Create pull request.
- Now you wait for Will to either accept your new download function or to ask you to make edits to it before including it in NaTDB.