git workflows - HeritageNetwork/Regional_SDM GitHub Wiki
All of the discussion here applies to the main
, aquatic
, and terrestrial
branches. terrestrial
is used in the examples, but the other branches can be applied interchangeably.
Get copy of repository
Helpful git commands
A simplified PR workflow
A PR workflow that maintains local edits
Ways to update without losing your work
expand
-
If you don't have one already, create a github account (here: https://github.com), log in.
- examples here will show username:
empetrum
- examples here will show username:
-
Navigate back to https://github.com/HeritageNetwork/Regional_SDM, choose
Fork
(button near upper-right). A fork is created in your user space and you'll see something like this in the upper left of the page when you are on the fork: -
Here, at your copy of the repo on github, click the button.
-
Choose
HTTPS
click the clipboard to copy the path.
- On the computer (or virtual machine) where you'll be doing the modeling, navigate, using Windows Explorer, to the location where you want the new copy of the repository
- Right-click inside the right panel of Windows Explorer, choose . If this option isn't available, install git, see https://github.com/HeritageNetwork/Regional_SDM/wiki/Software
- now use the HTTPS path you saved (above) to get a copy (clone) of your repository, preface it with
git clone
like this:
git clone https://github.com/empetrum/Regional_SDM.git
- it should look like this:
- Now you've got a full copy of the repo, in a folder named 'Regional_SDM' on your workstation.
- Type
cd Regional_SDM
to "change directory" into the repository folder.
- add the HeritageNetwork version of the repo as another "remote", call it
upstream
. git remote add upstream https://github.com/HeritageNetwork/Regional_SDM
Tim_Howard@MoBI01 MINGW64 /g/Users/tim_howard/Regional_SDM (main)
$ git remote add upstream https://github.com/HeritageNetwork/Regional_SDM
- make sure you have your user name and email set up in git, as described (last bullet) here (https://github.com/HeritageNetwork/Regional_SDM/wiki/User-Customizations)
- Passwords and credentials are crazy. This seems like the new way when using HTTPS.
- create a personal access token, as described here: https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-token
- copy and save that token (temporarily if you want), in a text file on your workstation.
- apply this setting
git config --global credential.usehttppath true
(allows a credential window popup) - caching your credentials might help (https://docs.github.com/en/get-started/getting-started-with-git/caching-your-github-credentials-in-git)
git config --global credential.helper wincred
expand
-
git checkout <branch>
aligns your files to a specific branch.
Tim_Howard@MoBI01 MINGW64 /g/Users/tim_howard/Regional_SDM (main)
$ git checkout terrestrial
Switched to a new branch 'terrestrial'
Branch 'terrestrial' set up to track remote branch 'terrestrial' from 'origin'.
-
git status
tells you where you are and what's going on
Tim_Howard@MoBI01 MINGW64 /g/Users/tim_howard/Regional_SDM (terrestrial)
$ git status
On branch terrestrial
Your branch is up to date with 'origin/terrestrial'.
nothing to commit, working tree clean
-
git branch
tells you what branches are in your repo. The star "*" shows what branch is checked out.
Tim_Howard@MoBI01 MINGW64 /g/Users/tim_howard/Regional_SDM (terrestrial)
$ git branch
main
* terrestrial
-
git remote -v
tells you what remotes you have set up. If you don't see the upstream branch, add it as described in #3 in the section above
Tim_Howard@MoBI01 MINGW64 /g/Users/tim_howard/Regional_SDM (terrestrial)
$ git remote -v
origin https://github.com/empetrum/Regional_SDM.git (fetch)
origin https://github.com/empetrum/Regional_SDM.git (push)
upstream https://github.com/HeritageNetwork/Regional_SDM (fetch)
upstream https://github.com/HeritageNetwork/Regional_SDM (push)
-
git log
shows you the last few commits of the branch you are working on. It also gives you another prompt:
which is confusing. At this prompt, if you hit the space bar, the log will advance a page; Enter will advance one line. To quit this prompt, typeq
. This bug may have been fixed, but if you accidentally type something else (such as ctrl-c) and return to the git prompt, but then you can't see your typing, typereset
press enter and you should be back in order (https://stackoverflow.com/a/43267044/435082 and https://stackoverflow.com/questions/44281617/git-text-invisible).
expand
If you make a change you want to be applied to the main repository, follow these steps:
- make the edit
- commit the change
- push that commit up to your own repo
- submit a pull request (PR) on the main repo. An owner 'accepts' the changes and completes the pull
- you then pull the updated version of the repo back to your local repository.
Here's a diagram of that workflow
Here are the commands.
- Make your edit. Here, I'll add a package to the
pkg_check.R
script. - Commit your change. This is easier in RStudio, but showing here using command line.
- The command is
git commit -m "update required packages"
. All commits require a message; I've added it here in-line for simplicity. - You first add the change
git add helper/pkg_check.R
, then commit it.
(git has autocomplete, so you can actually typegit add h<tab>p<tab>
)
- The command is
- Using command line, push your change up to your repo on github\
- the command is
git push origin terrestrial
"origin" is your remote repo, "terrestrial" is the branch you are pushing. Warning: use the full specification, not the shorthand "git push" because you have multiple remotes and you don't know where the unattributed push will go!\ - when asked for a password, enter your Personal Access Token. It should save it and you should be good from now on.
- the command is
- Now go up to your repo on github, you'll likely see a message like this:
- click
Compare & pull request
, then make sure the repos and branches are lined up like this, with the HeritageNetwork repo on the left and your repo on the right, and both of them are noting the correct branch. Add a title and comment on your changes.
- After filling this out, click the green button:
- I (and other owners, I think) get a message, we check it out, "approve" it, perhaps have a dialogue, then complete the pull request.
- click
- Because the pull is a commit, your local repo is out of sync with the HeritageNetwork repo, so, finally, pull down the current state of the repo to sync up. The command is
git pull upstream terrestrial
- Full loop complete!
This is how github diagrams the same workflow (at the repo on github, choose Insights -> Network). The straight yellow line is the terrestrial branch. Another user (Patrick) pulled the current version to his branch (arrow up to blue line), he then made some edits and submitted them back to the terrestrial branch, where they were merged back in (blue arrow down to yellow line).
The problem with a direct application of this workflow to our needs is that we also make changes to the code that we do not want pushed up to the HeritageNetwork repository. That adds extra complexity and requires us to step up to a whole new level.
expand
How to maintain our custom changes we don't want to be pushed up to the Heritage Network repository?
Overview: maintain a custom branch, make a change, cherry pick that change to your local copy of terrestrial, push it to your repo, PR it to HeritageNetwork repo, as follows:
- make a change in 'myProjectRepo'
- commit the change
- cherry-pick that commit to your local terrestrial branch
- push that commit up to your own repo
- submit a pull request (PR) on the main repo. An owner 'accepts' the changes and completes the pull
- you then pull the updated version of the repo back to your local repository.
Diagramming it:
Commands in detail:
- For completeness, I'll first make a new branch to keep my project-only modifications in, named
myProj
.
To do that, usegit checkout -b myProj
.
See here for more https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging.
- This branch has changes (to script 0, for example), that you don't want sent up to the main repo. Commit your changes separately so that the script 0 changes are in one commit (or more) and the change you want is in another commit. Here's an example for doing just that:
-
git status
to see that two files are changed -
git add
andgit commit
to commit the project-specific tweaks -
git add
andgit commit
to commit the fix we want pushed up to the main repo
-
- You need the commit ID for the one you want to push up to the main repo.
* Usegit log
for that, and then copy the commit ID (copy-paste is funny in command-line windows)
*q
at the:
to quit the git log prompt
* then switch to the terrestrial branchgit checkout terrestrial
*git cherry-pick
to get pull in the commit.
- Now follow the same workflow as above,
git push
to your repo online. Again, use the full specification:git push origin terrestrial
. - Submit a PR to the main repo
- Pull the newly updated repository down to your terrestrial branch
- I'll cover getting changes back into your project branch in the next section.
expand
There are many options, here are a few:
-
git cherry-pick
the commits -
git merge
the changes. -
git stash
thengit merge
thengit stash pop
- Merge your custom changes into a new copy of the terrestrial branch. Rename your project branch, make a new branch from terrestrial, apply your custom changes onto this new branch.
In more detail:
-
git cherry-pick
the commit.
* if there are only a few commits you want to get, this might be simplest.
* from the terrestrial branch, usegit log
to see the commit ID values. Thenq
to quit from the log prompt.
* The commit IDs are now on screen so you can switch to your branch and copy-paste in each commit after agit cherry-pick
\ -
git merge
the changes.
* Any file where there are changes on both branches will ask require you to edit those files and accept the changes from the branch you want.
* Simply edit the file, accepting the text from your branch. More details here: https://git-scm.com/docs/git-merge#_how_conflicts_are_presented.
* After fixing those conflicts, finish the merge. Example commands:
-
git stash
thengit merge
thengit stash pop
* Another way to deal with this is to not commit the changes you want to keep local. This can get confusing and possibly more difficult to track, but git has a way of "stashing" your changes that you don't want to commit and then giving you the opportunity to get them back later.
* More here: https://github.com/tghoward/images_test/blob/main/git_merge_into_myProj.png. Probably the most straightforward way to do this is:
*git stash
. Saves all your current changes in a special place. Allows you to leave the branch and do other things.
*git merge terrestrial
. Bring in the current state of the terrestrial branch.
*git stash pop
. Apply the stashed changes back on to your branch. Also remove these changes from the stash "place". This is a merge, so if there are conflicts, it will let you know and mark them.
- Merge your custom changes into a new copy of the terrestrial branch.
* The idea here is that you want to make absolutely sure all your changes are saved and applied on top of the scripts in the main repo.
* rename your current custom branch so you can keep using the same namegit branch -m myProj myProjOld
* make a new branch of the most recent version of terrestrialgit checkout -b myProj
(when in terrestrial)
* merge in myProjOldgit merge myProjOld
* delete myProjOldgit -d myProjOld
Here's a schematic of this last method. This method might make the most sense when a big update needs to be applied.
Finally, remember that googling git
commands can be very helpful - I usually find the stackOverflow sites the most helpful. Also the Pro-Git book is fully online and it and the git documentation are also excellent. https://git-scm.com/book/en/v2 .