A Git Style Guide
Translations are available in the following languages:
If you feel like contributing, please do so! Fork the project and open a pull request.
# good $ git checkout -b oauth-migration
bad - too vague
$ git checkout -b login_fix
# GitHub issue #15 $ git checkout -b issue-15
$ git checkout -b new-feature # good $ git checkout -b T321-new-feature # good (Phabricator task id) $ git checkout -b New_Feature # bad
$ git checkout -b feature-a/master # team-wide branch $ git checkout -b feature-a/maria # Maria's personal branch $ git checkout -b feature-a/nick # Nick's personal branch
Merge at will the personal branches to the team-wide branch (see "Merging"). Eventually, the team-wide branch will be merged to "master".
Tip: Use the following command while being on "master", to list merged branches:
$ git branch --merged | grep -v "\*"
git add -pto interactively stage specific portions of the modified files.
Don't split a single logical change into several commits. For example, the implementation of a feature and the corresponding tests should be in the same commit.
Commit early and often. Small, self-contained commits are easier to understand and revert when something goes wrong.
Commits should be ordered logically. For example, if commit X depends on changes done in commit Y, then commit Y should come before commit X.
Note: While working alone on a local branch that has not yet been pushed, it's fine to use commits as temporary snapshots of your work. However, it still holds true that you should apply all of the above before pushing it.
# good $ git commit
$ git commit -m "Quick fix"
Committing from the terminal encourages a mindset of having to fit everything in a single line which usually results in non-informative, ambiguous commit messages.
# good - imperative present tense, capitalized, fewer than 50 characters Mark huge records as obsolete when clearing hinting faults
fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.
It should also provide any pointers to related resources (eg. link to the corresponding issue in a bug tracker):
Short (50 chars or fewer) summary of changes
More detailed explanatory text, if necessary. Wrap it to 72 characters. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
Further paragraphs come after blank lines.
Bullet points are okay, too
Use a hyphen or an asterisk for the bullet, followed by a single space, with blank lines in between
The pointers to your related resources can serve as a footer for your commit message. Here is an example that is referencing issues in a bug tracker:
Resolves: #56, #78 See also: #12, #34
Ultimately, when writing a commit message, think about what you would need to know if you run across the commit in a year from now.
Similarly, if commit A solves a bug introduced by commit B, it should also be stated in the message of commit A.
--fixupflags respectively, in order to make the intention clear:
$ git commit --squash f387cab2
(Tip: Use the
--autosquashflag when rebasing. The marked commits will be squashed automatically.)
Do not rewrite published history. The repository's history is valuable in its own right and it is very important to be able to tell what actually happened. Altering published history is a common source of problems for anyone working on the project.
However, there are cases where rewriting history is legitimate. These are when:
That said, never rewrite the history of the "master" branch or any other special branches (ie. used by production or CI servers).
1. Make sure it conforms to the style guide and perform any needed actions if it doesn't (squash/reorder commits, reword messages etc.)
Rebase it onto the branch it's going to be merged to:
[my-branch] $ git fetch [my-branch] $ git rebase origin/master # then merge
This results in a branch that can be applied directly to the end of the "master" branch and results in a very simple history.
(Note: This strategy is better suited for projects with short-running branches. Otherwise it might be better to occassionally merge the "master" branch instead of rebasing onto it.)
# good - ensures that a merge commit is created $ git merge --no-ff my-branch
$ git merge my-branch
That said, it is important to actually choose a workflow and stick with it.
Be consistent. This is related to the workflow but also expands to things like commit messages, branch names and tags. Having a consistent style throughout the repository makes it easy to understand what is going on by looking at the log, a commit message etc.
Test before you push. Do not push half-done work.
Keep your repositories at a good shape by performing maintenance tasks occasionally:
This work is licensed under a Creative Commons Attribution 4.0 International license.