Git

These practices that apply to shared commits[1] (maybe after cleaning commits locally).

tl;dr

• Shared commits should not be changed.
• Changes in each shared commit should be closely related.

1. Don’t push your work until you’re happy with it

“One of the cardinal rules of Git is that, since so much work is local within your clone, you have a great deal of freedom to rewrite your history locally. However, once you push your work, it is a different story entirely, and you should consider pushed work as final unless you have good reason to change it. In short, you should avoid pushing your work until you’re happy with it and ready to share it with the rest of the world.”

– Git tools - rewriting history

See also:

• Whic git commands rewrite history?
• Cleaning unshared history: Squashing all commits in a branch.
• Cleaning unshared history with git rebase --interactive.
• Cleaning unshared history with git commit --amend.
• Cleaning shared history with git revert.
• Git playlist.

2. Keep commits focused

A commit should focus on related changes only. For example, fixing two different bugs should produce two separate commits. Small commits make it easier for other developers to understand the changes and roll them back if something went wrong. You can avoid sharing unwanted changes via .gitignore. If you can’t succinctly describe what the commit is doing in a few words, then it is likely too big. Small commits are easier to review, and easier to merge because they offer fewer opportunities for conflicts.

See also:

• The right size of a PR.
• Google engineering guide
• .gitignore templates.
• Undoing things with Git (video, lesson).

3. The work you share should be complete

Each commit and feature should do what it promises, completely; and reverting it should undo what that commit or feature meant to do, also completely. Before you commit changes, consider if other changes you’ve made are part of the same conceptual change and combine them into one commit rather than committing them separately.

4. Explain how to test the effect of the changes you made

Testing your code is important, particularly when sharing it with others. Automated tests are the best but not the only way to test the effects of the changes you made. When automated tests are excluded, the PR’s first comment should explain how you ensured that the code behaves as you expect, and how someone else may reproduce your results.

5. Structure each commit message like an email

Like an email, commit messages have a subject and an optional body. The subject should start with a line summarizing your changes (aim for 50 characters or less). Use the imperative, present tense – for example, “Fix typo”, not “Fixed typo” or “Fixes typo”. The message body, if present, should follow a blank line; wrap around 70 characters; and explain the motivation for the change (“why”, not “what” or “how”).

See also:

• Example of a commit message.
• Commit best practices.

6. Agree on a workflow

Choose a workflow based on your team’s needs and preferences. However you choose to work, just make sure to agree on a common workflow that everyone follows:

GitHub workflow:

This workflow is 2DII’s default. If a project uses a different workflow, document prominently (e.g. in README) what that workflow is (example).

• Uses a central repository.
• Uses a single long-lived branch: “main”; it never contains broken code.
• Developers work on “feature” branches (never on the “main” branch), share them via pull requests, and peers review the changes before they become a part of the central repository.
• A new release is created by tagging a particular commit on the main branch.

Gitflow workflow:

• Like the GitHub workflow but uses two long-lived branches: “main” and “develop”. The main branch stores the official release history, and the develop branch serves as an integration branch for features.

A team may agree on custom conventions beyond the “vanilla” workflows listed above. For example, you may agree to prefix a commit subject with “FIXME”, “AMEND”, or something else, to communicate with your team succinctly via a vocabulary you all share.

See also:

• Comparing workflows.

7. Use tools to be more productive

Rather than relying on memory or will power, rely on good systems. Good systems such as git aliases, hooks, and graphical user interfaces can help you work more productively, correctly, and comfortably.

See also:

• oh-my-zsh: Unleash your terminal like never before.
• gh: Take GitHub to the command line.
• Git from RStudio.

References

Version control best practices

How

• Git practices by example
• Coding helpdesk.
• GitHub’s Git guides.
• Coderefinery’s Git intro.
• Git best practices.
• Visualization of useful Git commands.

---

[1] A shared commit is a commit that someone other than you might access, for example, because you pushed it to a remote repository that someone else has permission privileges to access.