Git Workflow How To

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 braid into directory braid-foo and change to that directory.

git clone <braid-repo> braid-foo
cd braid-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

Then 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
...

Then 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

Then Create 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

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.
• Stash - This is for code that is already pushed. It has a really nice branch diffing tool.

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.