Git Cheat-Sheet¶

The following is a brief summary of the feature-branch workflow and important Git commands

To get a local working copy of a repository (typically a fork of XGC-Devel or XGC-Full-f)
```
git clone https://[username]@github.com/PrincetonUniversity/[repo name].git
```
- This will create a directory called [repo name] which contains the code of the branch master
- We do not work with the branch master itself; it is intended to hold the stable, verified version of the code and is updated only through pull requests.
- You have to either checkout a feature branch or create a new branch for your code development.
Get a branch (other than master) from the GitHub repository
- In directory [repo name] run
```
git checkout [branch]
```
- This will create a working copy of the branch [branch] in the remote repository on GitHub on your local computer. This working copy is a branch itself with the name [branch].
To display the branches available (only the ones that you have checked out before)
```
git branch
```
To display all branches (including branches that are not on your computer but only in the online repository), remote branches will have the prefix remotes/
```
git branch -a
```
To get remote branches to your local working copy
```
git fetch
```
To switch between branches
```
git checkout [branch]
```
You can get a list of commits with
```
git log
```
You can check out a specific commit by using the hexa-decimal number of that commit. Be sure that this commit was for your current branch.
```
git checkout [commit]
```
Suppose you want to add a feature to the code. To do this, you first checkout the branch you want to start from (typically: master) and then create a copy of it with a different name
```
git checkout [branch name]
git checkout –b [username]/[new branch name] [branch name]
```
- This creates a local branch called [username]/[new branch name] on your local computer, which is a copy of the branch [branch name] in the remote repository.
- Now you can work on your own branch. When you have finished something and want to keep it, you commit the modifications with
```
git commit –am 'a message explaining what you did'
```
- Keep in mind:
  - No commit message is better than a non-descriptive, generic commit message. So include details that help other users understand what a specific commit includes (especially if you fixed a bug).
  - Use the following format (use enter for line breaks; the commit is executed only after the closing single quote is entered):
    'Subject line: descriptive message'
- NEVER COMMIT DIRTY CODE
  - Make sure that your code compiles and runs before you commit.
  - By committing code that does not compile or run, you make it impossible to use useful tools like git bisect that helps to identify commits that introduced a bug.
  - If you have already made a commit and later discover that it does not compile, then it is still possible to correct this mistake so long as the commit has not been merged. Follow these instructions to rewrite history, typically via git commit --amend (for the most recent commit) or git rebase -i (for older commits).
- If you want to revert your modifications use
```
git checkout .
```
- To make your branch available for others on GitHub, you have to ‘push’ it to the remote repository
- To be safe (the branch you have been working on might exist already in the remote repository and others might have modified it) you should ‘pull’ from the remote repository first:
```
git pull origin [your current branch]
```
- This will merge any changes made by others to this branch into your local copy and will notify you if there are any conflicts.
- After resolving any conflicts and committing the corresponding changes using git commit, you are ready to push
```
git push origin [your current branch]
```
When you are done testing and verifying your modifications in your branch [username]/[branch name] and think it is ready to be merged into master
- First get an up-to-date copy of master
```
git checkout master
git pull origin master
git checkout [username]/[branch name]
```
- For safety (in case someone else is working on your branch):
```
git pull origin [username]/[new feature]
```
- Now merge master into your branch
```
git merge master
```
- Now push to the upstream repository (i.e. GitHub)
```
git push origin [username]/[new feature]
```
- Go to GitHub and create a pull request for your changes to be merged into master of the parent XGC repository and select appropriate reviewers and notify them of you pull request.
If you like, implement the scripts git-completion.bash and git-prompt.sh (in the directory utils/git_tools in the repository) in your shell environment. The first will add GIT command completion to your shell. The second will display a prompt indicating your current branch and other useful information once you cd to a GIT repository. Instructions for the installation of these scripts is included in the scripts. A small example:
```
11:47 core_dev ~/Work/Code_development/HBPS Project/XGC-Full-f/XGC-0$
```
- To use those scripts add the following lines to your ~/.bashrc (~/.profile on OSX)
```
[ -f ~/bin/git-prompt.sh ] && . ~/bin/git-prompt.sh \
PS1="\A$bold$magenta\$(ret=\$?; [ \$ret -ne 0 ] && echo -n \" \$ret\")$nbold $red\h $cyan\$(__git_ps1 '%s') $green\w$normal\\$ " \
source ~/bin/git-completion.bash</code>`
```