Git Workflow

Some of this document is motivated by the GitFlow model.

Adding New Features

Most features and code changes should be developed on a separate branch. Once the feature is finished, tested, and approved, it will be merged back into the master branch and the development branch will be deleted. Here is an example workflow for feature "foo":

Create New Development Branch

Clone hypre into directory hypre-foo and change to that directory.

git clone <hypre-repo> hypre-foo
cd hypre-foo

Create new branch foo (if not already present) and change to that branch.

git branch foo
git checkout foo

If co-developing the feature with others, create a shared remote branch and make sure that push/pull track the remote branch (the -u option).

git push -u origin foo

Develop code

git status       # See the status of code changes in the branch
git add <files>  # Stage files to be commited to the branch
git commit       # Commit changes
...
git push         # Push changes to the remote branch to share with co-developers
...
git pull         # Pull co-developer changes from remote branch
...

Test the code.

It may be useful to merge the master branch into the feature branch at this point, especially if lots of changes were also made on master. Use the --no-ff option any time a merge of two different branches is done, because it produces better branching visualization and history.

git checkout master       # Change to the master branch
git pull                  # Pull in any new changes made to the master branch
git checkout foo          # Change back to the foo branch
git merge --no-ff master  # Merge master into the foo branch

Create a pull request

Create a pull request to finalize changes before merging into the master branch.

Before merging, it is wise to first update the feature branch (as outlined above) if it is behind the master, then run additional tests (even if the code itself has no conflicts, behavior changes are possible).

Once the pull request is approved, merge the feature into the master branch by selecting Squash and merge from the drop-down list on the Merge pull request button near the bottom of the page. This will create a single new commit on the master branch for the merge. Please take the time to rewrite the default commit message produced by GitHub (for pointers on writing effective commit messages, see below). The general form of the message should be something like :

Title for this commit (#pull-request-number-goes-here)

This is an informative stand-alone description of the commit that replaces the itemized commit messages that GitHub inserts by default.

Select Confirm squash and merge when ready to complete the merge.

Delete the feature branch after the merge. The easiest way to do this is by clicking a button from within the pull request. Alternatively, the branch can be deleted from the branch listing page. GitHub will automatically provide a Restore branch button in the closed pull request. It is a good idea to delete your local branch as well, but you will need to use the -D option to avoid error messages related to the squash merge (see this link for an explanation).

git branch -D foo

Pull requests from users outside the main development team

There are a couple of ways to handle these pull requests (PRs). If the PR is straightforward, it can be reviewed and merged directly into master as described above. For a more significant PR, a development branch should be created for further development and testing:

• Collaborator creates pull request PR-orig (usually this is set to merge to master)
• Hypre developer creates development branch PR-dev-branch based on master
• Hypre developer changes merge branch for PR-orig: Click Edit, select PR-dev-branch from drop-down menu, and Save
• Hypre developer merges PR-orig into PR-dev-branch (do not use a squash merge in this case to maintain original log)
• Hypre developer creates pull request PR-dev from PR-dev-branch and refer back to PR-orig (explicitly reference its number)
• Hypre developer closes PR-orig

Notes on branch-to-branch merges

Sometimes it is useful to use a branch to update another branch, especially when major features are being developed. In these cases, it is usually better not to use squash-merge, because git may lose track of its relationship to master. That is, even if a branch is up to date with master, after a squash-merge into another branch, that may no longer be the case. This is explained in more detail here. In short, using a squash-merge from branch to branch is still okay in certain situations, but be careful when doing it, because additional conflict resolution may be necessary.

Useful Git Commands and Information

See a list of local and remote branches and which is the current branch.

git branch --all

See the commit log in a graphical format showing the branch history.

git log --graph --oneline --decorate --all

Other useful ways to visualize branch history, commit diffs, ...

• Gitk - Use locally on the command line (i.e., gitk or gitk --all). Consider setting up (and saving) a custom view with View -> New view that shows "All refs" at a minimum.
• GitHub - This is for code that is already pushed. Add ?w=1 to the end of the URL of a code diff to ignore whitespace.

Writing Effective Git Commit Logs

When entering commit log information, type in a short descriptive title line following by a blank line then any additional information that may be useful. Git will use the title line in commands like git log --graph --oneline above. More discussion on how to write an effective git log message can be found here.