GithubHelp home page GithubHelp logo

git-style-guide's Introduction

Git Style Guide

This is a Git Style Guide inspired by How to Get Your Change Into the Linux Kernel, the git man pages and various practices popular among the community.

Translations are available in the following languages:

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

Table of contents

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

Branches

  • Choose short and descriptive 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 GitHub issue) 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 uppercase letters are a valid exception. Use hyphens 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 the same feature, it might be convenient to have personal feature branches and a team-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, unless there is a specific reason not to.

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

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

Commits

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

    Tip: Use git add -p to 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.

Messages

  • 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 everything in a single line which usually results in non-informative, ambiguous commit messages.

  • The summary line (ie. the first line of the message) should be descriptive yet succinct. Ideally, it should be no longer than 50 characters. It should be capitalized and written in imperative present tense. It should not end with a period since it is effectively the commit title:

    # good - imperative present tense, capitalized, fewer than 50 characters
    Mark huge records as obsolete when clearing hinting faults
    
    # bad
    fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.
  • After that should come a blank line followed by a more thorough description. It should be wrapped to 72 characters and explain why the change is needed, how it addresses the issue and what side-effects it might have.

    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
    
    Source: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
    

    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.

  • If a commit A depends on commit B, the dependency should be stated in the message of commit A. Use the SHA1 when referring to commits.

    Similarly, if commit A solves a bug introduced by commit B, it should also be stated in the message of commit 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 be squashed automatically.)

Merging

  • 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:

    • 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 onto the "main" in order to merge it later.

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

  • Keep the history clean and simple. Just before you merge your branch:

    1. Make sure it conforms to the style guide and perform any needed actions if 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-running branches. 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 a fast-forward:

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

Misc.

  • 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 your development procedures.

    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.

  • Use annotated tags for marking releases or other important points in the history. Prefer lightweight tags for personal use, such as to bookmark commits for future reference.

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

License

cc license

This work is licensed under a Creative Commons Attribution 4.0 International license.

Credits

Agis Anastasopoulos / @agisanast / http://agis.io ... and contributors!

git-style-guide's People

Contributors

agis avatar alik0211 avatar alxsimo avatar aspenforester avatar avatar-lavventura avatar barik avatar bc-bfenton avatar calinou avatar danielkaparunakis avatar davidkadaria avatar denysdovhan avatar dijonkitchen avatar jeffvandyke avatar jeko2000 avatar juanitofatas avatar mbiesiad avatar runjak avatar simon-johansson avatar vanillajonathan avatar vincendep avatar vsemozhetbyt avatar wooorm avatar zorbash avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

git-style-guide's Issues

Bullet list style

  - Typically a hyphen or asterisk is used for the bullet,
    preceded by a single space, with blank lines in
    between, but conventions vary here

In your example, the hyphen is preceded by two spaces.

Bad guidelines for commit length/grammar.

Current style guide defines a 50-character limit for commits (and explicitly states that bad grammar should be used:

The commit summary line should be descriptive yet succinct. It should be no longer than 50 characters. It should be capitalized and written in imperative present tense. If it is a single sentence, do not put a period at the end:

  1. 50-character limit is quite non-standard, the current standard being 70-75. This is even used for linux (source (note that this guideline is actually even used by the author of git). If there's a sane reason to define 50 as a new maximum, that reason needs to be clearly stated.
  2. There's no sane reason to explicitly suggest bad grammar (omit the period). If the suggestion is to avoid proper grammar, a very good reason should accompany it (why should users follow a random guideline which suggests going against standards?).

I'm not necessarily suggesting that these two points be removed: but if the intentions is to keep them (and go against pre-existing standards), a sane reason should accompany them.

Brazilian Portuguese Version

Hi, I'd like to create a pt-br version. What do you think about create another .md file like "style-guide-pt-BR.md"?

Better description of vim

Hey! I think people are routinely confused by vim because it appears to do nothing after you've written something. You may want to clarify the messages section to note what happens after you've written the description of a commit. i.e. now press :q to quit vim, etc.

Recommend that branch names be lowercase?

It seems to be a pattern with branch names in this guide, but is it a good rule to make sure that branch names stay lowercase for the most part? If so, it should probably be written.

At this point, I'm polling the community before making a pull request.

Required emphasis - all of this applies only to pushed commits/branches

In my opinion, it's perfectly fine to have a messy local copy, and clean it up later on:

XKCD 1296

In particular, this applies to the "Commits" section, and the "Messages" section. It's perfectly reasonable to use local commits as temporary snapshots of your work, fixing a bug and implementing a feature simultaneously; it's only important that you rewrite history before pushing - in this case to two simple commits, one for the bugfix and one for the feature (if they can indeed be logically separate).

This is in no way meant to detract from the "do not rewrite published history" rule.

Which style should I use to add links into commit?

In the guide you have given following example for links:

Source http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Is it recommended to use : after source as:

Source: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

and also use Link instead of source?

ex:

Link: www.google.com

Chinese Version

I think it is a very good guide for me to manage my team.
Now I translate it into Chinese, and I want to know how to
merge into your repo.

Git rebase not working as expected (Label:Question)

Hello have doubt regarding git rebase .

I have two branches one main and another my feature branch .

I made 3 commit on feature branch at 1pm 2pm and 3pm respectively, now I did the 4th commit on main-dev at 4pm , When I am on feature branch and running git rebase main , on top of 4th commit my 3 commits are there absolutely as expected , but here comes the problem as soon as I am running git push my feature branch is getting diverged and then getting merged into feature again .

Can you help here , why it is happening.

Below screenshot for reference

Image description

Editor wise commit message formatting

Hi @agis-,

This is some nice stuff here.

In the Commit Messages section, what do you think about having something to auto-format git commit messages that people can use in their choice of editors like Vim or Emacs etc.

I use Vim for my things so I have a separate auto command to wrap messages in 72 characters per line and for spell check also.

I thought asking you would be right before a pull request as I saw in another issue that you were talking about keeping only git related things in the guide not editor specific.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.