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
We do not work with the branch
masteritself; 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
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
To display the branches available (only the ones that you have checked out before)
To display all branches (including branches that are not on your computer but only in the online repository), remote branches will have the prefix
git branch -a
To get remote branches to your local working copy
To switch between branches
git checkout [branch]
You can get a list of commits with
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 bisectthat 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
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
First get an up-to-date copy of
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
[ -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>`