Git and GitHub

Git Tutorial

• an introduction to git by Manuel Zeise
• octocat introduction
• https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github
• http://cms-sw.github.io/faq.html
• GitFixUm

Useful GitHub documentation

• Markdown Cheatsheet
• Markdown Live Preview

Basics

Replace <...> according to your needs. [...] indicates optional arguments.

ssh Key

• After you created your github account first set your global username, follow the steps overhere: https://help.github.com/articles/setting-your-username-in-git/
• Then set your global email, https://help.github.com/articles/setting-your-commit-email-address-in-git/

Now we want to set up the ssh keys, therefore we have to generate a new key. If there should occur any questions you can as always ask one of your colleagues

• First follow the commands over here: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/. use ~/.ssh/ as your directory where to put id_rsa file.

• next add this to your github account, by following the steps overhere: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/. DONT DO THE FIRST STEP WHERE SUDO IS USED, instead open your created public ssh file, ~/.ssh/id_rsa.pub, with an editor and copy everything in there. and paste this to the key field in step 6.

• to verify the key follow the steps overhere: https://help.github.com/articles/testing-your-ssh-connection/ note that if you see the message: Hi username! You've successfully authenticated, but GitHub does not provide shell access. the key is working

Now we can checkout the packages as decribed over here: https://github.com/cms-analysis/HiggsAnalysis-KITHiggsToTauTau/wiki/Analysis-checkout-scripts

Clone (check out) an existing repository

git clone <URL> [<local path>] [-b <branch>]

Pull changes from the remote server

git pull [origin <branch>] # does not work in several CMSSW releases after cmsenv
git fetch origin && git merge origin/<branch>
git pull --rebase [origin <branch>]

Commit changes to the remote server

git add -p # add changes hunk by hunk to the staging area
git status && git add <file> # add files that are not yet known to git or not covered by the command above
git commit -m "<message>" # the message should help to identify the commit and its purpose even after years
git push [origin <branch>]
----
git reset <file> # to undo "git add" before commit

Stashes

git stash [-p] # put local changes aside on a stash
git stash pop # get back these changes
git stash drop # drop changes without applying them locally

Merge conflicts

git mergetool --tool meld
(export PATH=/usr/bin/:$PATH && git mergetool --tool meld) # CMSSW version due to problems with meld
(export PATH=/usr/bin/:$PATH && export LD_LIBRARY_PATH=/opt/ogs/lib/linux-x64 && git mergetool --tool meld) # In case of a problem of meld (like Seg. Fault.) try this! it has been seen to have this problem in CMSSW_9X releases.

If a merge conflict appears during git stash pop you need to do

git reset HEAD
git stash drop

after resolving them. Use gitk --all to make sure that you do not loose uncommitted code.

Merging Master into development branch

git checkout <branch>
git merge origin/master
git commit
git push

Forked Repositories

• Pull/push changes from a forked repository:

git remote add upstream <https://github.com/...> # only once
git pull upstream <branch>
git push [origin <branch>]

• Pull/push tags from a forked repository:

git fetch --tags upstream <branch>
git push origin <tag>

Get back a dropped stash

In case you dropped a stash (or a commit?) by mistake and want to get it back, first do

git fsck --no-reflog | awk '/dangling commit/ {print $3}'

This will print you some hashes most probably including the hash of your stash. Look at them with

git show <hash>

and apply the stash with

git stash apply <hash>

Taken from stackoverflow.

Partially revert a commit

git stash
git revert <commit> --no-commit
git reset HEAD
git add <files/patches to be reverted>
git commit -m <message>
git stash && git stash drop
git stash pop

Taken from stackoverflow.

Tipps

• Avoid GUI asking for username and password for commits/pulls: git config --global core.askpass ""
• It can be convenient to let git cache the passwords for you. You can enable this feature via git config --global credential.helper cache""
• The timeout for caching the passwords can be adjusted with git config --global credential.helper 'cache --timeout=3600'. In this example the timeout is set to 3600s=1h.
• If you have a local commit and pushing it fails because there have been developments on the remote, pull with the rebase option to avoid unnecessary merge commits:

git pull --rebase

• Windows popping up to ask for username and passwort after git push/pull can be avoided and replaced by a bash prompt. unset SSH_ASKPASS""

• If only some of the commits in the development branch are useful, just cherry-pick them to another branch:

git checkout master
git cherry-pick 1c8ac576fadc49
git push

• Make sure to be on the newest commit possible when creating a new branch
• Use gitk or a comparable tool to have a graphical representation
• git rebase"" can not be used if the branch has already been commited – better do not use it at all but git pull --rebase"" all the time
• resolve merge conflicts with git mergetool –tool=meld""
  • Mind that this only works in a window without CMSSW. The Version in the middle is the result of your merge efforts. Save it and commit the changes, then your merge is successful
• See interactively what you are commiting: git add -p
• Use local commits in branches you will not push. This is useful e.g. for setting of local paths
• The stashing procedure is very useful. The related commands are.

git stash
git stash pop
git stash drop

to remove uncommited changes, get them back or completely forget them

Collaboration Guidelines

The following points summarizes everything that concerns the collaboration on the analysis framework itself as well as the derived analyses.

Every analysis group member is reachable on the mailing list [email protected].

Shared Ressources

All shared resources (configurations, weight files, etc) should be uploaded in the corresponding repositories.

Git branching model

The principle is, that each development should be finished with care and if possible checked by someone else. Each commit on the master branch should be compiling and bugs are fixed as soon as they pop up.

Advantages

• Overview: A feature branch provides a better overview since developments are compact in one place compared to a svn-like structure
• Collaboration: In feature branches, you can do commits of things that do not yet work or even compile. That way, you can ask someone for help
• Encapsulation: While working on a feature branch, you have stable conditions and are not effected by changes from others – on the other hand, you can not break anything in the master

Workflow

Workflow for new features:

• Create a feature branch and push your commits there
• Merge the master branch in your feature branch frequently to avoid severe merge conflicts
• If you think the feature is ready, write a mail to the kit-higgs list (and eventually Artus if it is involved) with a short explanation what the feature does and how to use it
• Either anyone on the mailing list will pick this up and get in contact with you within 24 hours or you can feel free to merge the feature on your own
• Present the new feature in the Wednesday meeting, including a quick tutorial

Workflow for bugfixes:

• Just commit them to the master branch
• If the bug has caused bad results, inform the mailing list

Workflow for fundamental changes is like the workflow for new features, but:

• inform the mailinglist before you start working on it and ask for feedback
• inform the mailinglist once you are ready and merge the master in your branch to solve merge conflicts. Ask the other who has been working on the master for help.
• Present in the Wednesday meeting
• If no one complains after an adequate time, merge your feature into the master