Git‎ > ‎

Advice (Please Read)

Working with git is very similar to working with many other versioning systems, and they often all have the same general rules for how they are to be used.  So, while these bits of advice are not specific to git, you should probably still stick to them when you use git.

Make Atomic Changes

It is best to have your commits deal with one specific thing at a time.  It greatly helps with conflict resolution and is also an aid when reviewing the history of a file.  A single feature, a bugfix, or a new class are all things that could be considered "atomic" in nature.  Avoid making gigantic commits where dozens of changed files are sent into the repository as a single entry.  Also avoid making a bugfix commit without testing it and then having to commit a bugfix for your bugfix.

Make Descriptive Commit Logs

Someone looking at a commit is able to answer four of the five questions: who, what, where, and when.  The only question that's unable to be answered is why.  Your message should always answer some sort of a why question.
  • Why was the commit made?
  • Why did you choose to pick your particular solution instead of some other approach?
  • Why was some particular situation overlooked?
  • Why are we reverting working code?
If people do not understand the code of your commit, a human-readable version goes a long way towards enlightenment.  To follow the git standard, the first line of your commit message should be similar to the subject line of an email: short and to the point.  After that, add a blank line and then describe the commit in detail.

Review Your Commit

Before you log your changes into the repository for all time, you should double-check that only what you intended to be saved is actually in the commit.  People will often commit too many changes, debug code, or accidentally omit files.  Git assists developers by showing a list of files that are going to be committed, a list of other files that are not going to be committed but still have changed, and a list of files that are not tracked.  Make sure you review git status and ensure the files listed all look correct.  Using git diff to review changes before they are committed also helps.  When you commit, take a look at the number of lines changed and the files in the prepared commit message to see if that's reasonable before you use git push and send your changes along to another repository.

Make Branches

Git makes it easy to spin off your own feature branch.  If you deal with more than a couple files, if you could be changing how something works underneath, or if you might want to throw this work away, I strongly suggest that you use a branch.  Branches are trivial to create and are easy to merge.  If desired, the entire branch can be thrown away or shared with others.

I also suggest you use a good branching strategy.  You can even supplement your branching strategy with git's hooks and additional programs, such as how gitflow works.

Pull and Merge Constantly

When working for a while without pushing in your changes, you should git pull or git merge changes into your branch.  This will help keep the delta since the last merge at a minimum, thus making conflicts easier to solve.  It is far better to resolve smaller conflicts and constant merging will force the conflicts to be smaller.