git_setup - PNHP/Regional_SDM GitHub Wiki

get up and running with git

Assumption: you are using MS Windows. (but you can do this on any other OS, too)

I think the most appropriate system for us to use is the "Integration Manager Workflow" control system, described here: https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#Integration-Manager-Workflow. The big picture workflow is this: users "fork" the repository to their own github site, clone their fork locally, make edits, push those changes to their fork online, then make a pull request (PR) to the master repository. This way the master repository easily integrates all our tweaks and also allows us to backtrack at any time to any previous state. You can also start from fresh any time with a new download from the master repository.

  1. install github for windows, available here (https://desktop.github.com/). It will put two icons on your desktop, GitHub and Git Shell
  2. with a browser, navigate to here https://github.com/NYNatHeritage/Regional_SDM, find the Fork button in the upper right hand corner, fork this repository to your own (or your organizations) github site. Find your fork at your site, click the clone or download button, copy the text shown there (use it two steps down).
  3. locally on your computer, run Git Shell, change directories over to the place you want to store this repository (cd to change directory)
  4. type or paste this command git clone https://github.com/<<your username here>>/Regional_SDM.git using the path you copied two steps up.
  5. voila, you now have a full and completely updated copy of the scripts in this folder. They are one folder down in the repository name (Regional_SDM)
  6. one last setup step. On your desktop, git knows the location of your fork, but not the location of the original repository. Use this command to set it git remote add upstream https://github.com/NYNatHeritage/Regional_SDM.git More on this here: https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes
  7. you don't do any editing or script running in git - git is only for tracking changes in those files in the repository. So now open and run the scripts in your favorite R editor, such as R Studio.

Git basics for this project

  1. in Git Shell, change directories into the repository folder, something like cd G:\RegionalSDM\scripts\Regional_SDM
  2. in R Studio (or whatever your editor is), try running one of the scripts, improve it as needed, save it. Let's say you've modified the file "preproc_makeABrick.R."
  3. back in Git Shell, in the repository, type git status, it will tell you the file has been altered.
  4. type git add preproc_makeABrick.R to stage the file for commit.
  5. type git commit You will have to write a commit message so a text editor will likely open up and ask for a commit message. A very short comment is appropriate. Because text editor integration may be funny (e.g. not work, but see this link to fix it) in windows in this case, I tend to just add the message along with the commit command, with a -m switch, like this: git commit -m "my first commit!"

Updating your fixes to the repository online

The whole point for using this system is that it can handle ALL of our edits and fixes seamlessly and make sure edits don't get overwritten and everyone's fixes are integrated. Emailing scripts around to each of us would very rapidly become a mess.

  1. now that you have a modified file in your local copy of the repository and you have committed that change, you want to get it up to the master.
  2. the first step is to ship it to your fork. Use git push origin master for that. Here, you are telling git to push the master branch up to the remote repository named origin (which is your fork of the original).
  3. now go online to your fork, for me that's https://github.com/tghoward/Regional_SDM
  4. At the main page for your fork it should say something like "This branch is 1 commit ahead of NYNatHeritage:master". Right above this note, there will be a grey button that says new pull request. Click it. It should set the 'base fork' as our master and the 'head fork' as your copy. Add a comment if you like, then click create pull request. That's it. Then someone (right now, Tim, but we could make it everyone if we want) merges that pull request and these changes are applied.