Best Practices

Updated at 2016-12-20 22:54

Basic Git workflow in 11 steps. This is how it goes if you have a small team and do not require to handle pull requests.

  1. Pull the most recent master branch from a shared remote repository.
  2. Create a local branch taskname for your current task, e.g. fix/bugname.
  3. Code and drink Pepsi.
  4. Commit changes to your local branch taskname.
  5. Commit interval should be close to ten minutes until the task is complete.
  6. Try out the program, run the tests and go to 3 if an error is found.
  7. Switch to your local master branch.
  8. Pull most recent master from shared remote repository REMOTE.
  9. Merge master with branch taskname.
  10. Delete branch taskname.
  11. Push master to shared remote.

Commit often. Git uses local repositories so it makes more sense to make small commits. You should commit once every 5 minutes, learn this by setting a timer. Do not commit anything that breaks the build or disables running the program.

A commit should only contain closely related changes. Fixing two different bugs should result in two different commits, even if they are small. Use staging area for your advantage. Usually having "and" or multiple sentences in your commit message mean that the commit could be smaller.

Commit message should be short and to the point. Message subject should first state what the commit changes in 50 characters. Use present tense imperative for the title. Consistent with automatically generated messages like git merge. Think commits as patches that will always change X to Y. It is generally shorter than the alternatives. If you must, for some reason, include a bigger message, use one blank line to separate additional message from the commit message title and write as much as you like. Wrap additional message at 70 characters.

git commit -m "Fix login bug B-2134"
git commit -m "Update copyright year"
git commit -m "Add formatting library initial version"

Define common prefixes for commit messages.

git commit -m "Add something"
git commit -m "Remove something"
git commit -m "Remove something"
git commit -m "Refactor something"
git commit -m "Update something"
git commit -m "Add something"

Don't commit generated files. Don't commit anything that can be generated from the other files e.g. CSS files that are generated from SASS or compiled binaries.

Public commit history should not be changed. After you have pushed to a shared repository, it is much safer to treat them as commits that cannot be changed. If any bugs rise up, fix them with new reverting commits. Only allow true masters to fiddle with shared repositories. Use rebase only on commits that none else has seen as it rewrites history.

Test the commit before you push. Push to shared repository only after you have a fully working version.

Splitting an already existing repository into smaller ones is troublesome. Consider deciding how many repositories will you use at the start of the project. You can manage these into one super project with e.g. git-submodules or gitslave.

  • Code that might be reusable should have their own repository.
  • Even one product can be divided in multiple repositories e.g. by libraries or classes.
  • Large binary files should have own repository as git is slow with them.

Maintenance is good. You should do periodic maintenance on your local and shared repositories:

# Check if repository is valid.
git fsck
# Reduce your repository size.
git gc
# Check if you have any stashed changes.
git stash list

Perfect your configuration:

  • Learn a graphical interface e.g. gitweb, ungit, SourceTree or GitHub.
  • Setup bug tracking software that integrates with Git.
  • Setup hooks with Git e.g. automatic pulling.
  • Specify who has access to important branches e.g. use gitolite tool to define access control for master branch.