Repository files navigation

This is a Git Style Guide inspired byHow to Get Your Change Into the LinuxKernel,thegit man pages and various practices popularamong the community.

Translations are available in the following languages:

• Chinese (Simplified)
• Chinese (Traditional)
• French
• Georgian
• German
• Greek
• Italian
• Japanese
• Korean
• Polish
• Portuguese
• Russian
• Spanish
• Thai
• Turkish
• Ukrainian

If you feel like contributing, please do so! Fork the project and open a pullrequest.

1. Branches
2. Commits
3. Messages
4. Merging
5. Misc.

• Chooseshort anddescriptive names:

  # good$ git checkout -b oauth-migration# bad - too vague$ git checkout -b login_fix

• Identifiers from corresponding tickets in an external service (eg. a GitHubissue) are also good candidates for use in branch names. For example:

  # GitHub issue #15$ git checkout -b issue-15

• Use lowercase in branch names. External ticket identifiers with uppercaseletters are a valid exception. Usehyphens to separate words.

  $ git checkout -b new-feature# good$ git checkout -b T321-new-feature# good (Phabricator task id)$ git checkout -b New_Feature# bad

• When several people are working on thesame feature, it might be convenientto havepersonal feature branches and ateam-wide feature branch.Use the following naming convention:

  $ git checkout -b feature-a/main# 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 "main".

• Delete your branch from the upstream repository after it's merged, unlessthere is a specific reason not to.

  Tip: Use the following command while being on "main", to list mergedbranches:

  $ git branch --merged| grep -v"\*"

• Each commit should be a singlelogical change. Don't make severallogical changes in one commit. For example, if a patch fixes a bug andoptimizes the performance of a feature, split it into two separate commits.

  Tip: Usegit add -p to interactively stage specific portions of themodified files.

• Don't split a singlelogical change into several commits. For example,the implementation of a feature and the corresponding tests should be in thesame commit.

• Commitearly andoften. Small, self-contained commits are easier tounderstand and revert when something goes wrong.

• Commits should be orderedlogically. For example, ifcommit X dependson changes done incommit Y, thencommit Y should come beforecommit X.

Note: While working alone on a local branch thathas not yet been pushed, it'sfine to use commits as temporary snapshots of your work. However, it stillholds true that you should apply all of the abovebefore pushing it.

• Use the editor, not the terminal, when writing a commit message:

  # good$ git commit# bad$ git commit -m"Quick fix"

  Committing from the terminal encourages a mindset of having to fit everythingin a single line which usually results in non-informative, ambiguous commitmessages.

• The summary line (ie. the first line of the message) should bedescriptive yetsuccinct. Ideally, it should be no longer than50 characters. It should be capitalized and written in imperative presenttense. It should not end with a period since it is effectively the committitle:

  # good - imperative present tense, capitalized, fewer than 50 charactersMark huge records as obsolete when clearing hinting faults# badfixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.

• After that should come a blank line followed by a more thoroughdescription. It should be wrapped to72 characters and explainwhythe change is needed,how it addresses the issue and whatside-effectsit might have.

  It should also provide any pointers to related resources (eg. link to thecorresponding issue in a bug tracker):

  Short (50 chars or fewer) summary of changesMore detailed explanatory text, if necessary. Wrap it to72 characters. In some contexts, the firstline is treated as the subject of an email and the rest ofthe text as the body.  The blank line separating thesummary from the body is critical (unless you omit the bodyentirely); tools like rebase can get confused if you runthe 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  betweenThe pointers to your related resources can serve as a footerfor your commit message. Here is an example that is referencingissues in a bug tracker:Resolves: #56, #78See also: #12, #34Source: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

  Ultimately, when writing a commit message, think about what you would needto know if you run across the commit in a year from now.

• If acommit A depends oncommit B, the dependency should bestated in the message ofcommit A. Use the SHA1 when referring tocommits.

  Similarly, ifcommit A solves a bug introduced bycommit B, it shouldalso be stated in the message ofcommit A.

• If a commit is going to be squashed to another commit use the--squash and--fixup flags respectively, in order to make the intention clear:

  $ git commit --squash f387cab2

  (Tip: Use the--autosquash flag when rebasing. The marked commits will besquashed automatically.)

• Do not rewrite published history. The repository's history is valuable inits own right and it is very important to be able to tellwhat actuallyhappened. Altering published history is a common source of problems foranyone working on the project.

• However, there are cases where rewriting history is legitimate. These arewhen:

  • You are the only one working on the branch and it is not being reviewed.

  • You want to tidy up your branch (eg. squash commits) and/or rebase it ontothe "main" in order to merge it later.

  That said,never rewrite the history of the "main" branch or any otherspecial branches (ie. used by production or CI servers).

• Keep the historyclean andsimple.Just before you merge your branch:

  1. Make sure it conforms to the style guide and perform any needed actionsif it doesn't (squash/reorder commits, reword messages etc.)

  2. Rebase it onto the branch it's going to be merged to:

     [my-branch] $ git fetch[my-branch] $ git rebase origin/main# then merge

     This results in a branch that can be applied directly to the end of the"main" branch and results in a very simple history.

     (Note: This strategy is better suited for projects with short-runningbranches. Otherwise it might be better to occassionally merge the"main" branch instead of rebasing onto it.)

• If your branch includes more than one commit, do not merge with afast-forward:

  # good - ensures that a merge commit is created$ git merge --no-ff my-branch# bad$ git merge my-branch

• There are various workflows and each one has its strengths and weaknesses.Whether a workflow fits your case, depends on the team, the project and yourdevelopment procedures.

  That said, it is important to actuallychoose a workflow and stick with it.

• Be consistent. This is related to the workflow but also expands to thingslike commit messages, branch names and tags. Having a consistent stylethroughout the repository makes it easy to understand what is going on bylooking at the log, a commit message etc.

• Test before you push. Do not push half-done work.

• Useannotated tagsfor marking releases or other important points in the history. Preferlightweight tagsfor personal use, such as to bookmark commits for future reference.

• Keep your repositories at a good shape by performing maintenance tasksoccasionally:

  • git-gc(1)
  • git-prune(1)
  • git-fsck(1)

This work is licensed under aCreative Commons Attribution 4.0International license.

Agis Anastasopoulos /@agisanast /http://agis.io... andcontributors!