• Stars
    star
    915
  • Rank 48,605 (Top 1.0 %)
  • Language
  • Created over 7 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Git commit message: how to write a great git commit message and commit template for version control

Git commit message

To write a great git commit message, take a look at these guidelines and suggestions.

Contents:

Top priorities

For the best git commit messages:

  • Read these guidelines and suggestions, then discuss them with your teammates.

  • Emphasize clear communication, because commit messages help you and your teammates.

  • Use a git commit template, such as ours here.

Begin with a short summary line

Begin with a short summary line a.k.a. message subject:

  • Start with an imperative present active verb: Add, Drop, Fix, Refactor, Optimize, etc.

  • Use up to 50 characters; this is the git official preference.

  • Finish without a sentence-ending period.

Continue with a longer description

Continue with a longer description a.k.a. message body:

  • Add a blank line after the summary line, then write as much as you want.

  • Use up to 72 characters per line for typical text for word wrap.

  • Use as many characters as needed for atypical text, such as URLs, terminal output, formatted messages, etc.

  • Include any kind of notes, links, examples, etc. as you want.

Summary examples

Summary examples of good commit messages:

  • Add foo

  • Drop foo

  • Fix foo

  • Refactor foo

  • Optimize foo

Summary keywords

We recommend these summary keywords because they use imperative mood, present tense, active voice, and are verbs:

  • Add: Create a capability e.g. feature, test, dependency.

  • Drop: Delete a capability e.g. feature, test, dependency.

  • Fix: Fix an issue e.g. bug, typo, accident, misstatement.

  • Bump: Increase the version of something e.g. a dependency.

  • Make: Change the build process, or tools, or infrastructure.

  • Start: Begin doing something; e.g. enable a toggle, feature flag, etc.

  • Stop: End doing something; e.g. disable a toggle, feature flag, etc.

  • Optimize: A change that MUST be just about performance, e.g. speed up code.

  • Document: A change that MUST be only in the documentation, e.g. help files.

  • Refactor: A change that MUST be just a refactoring patch

  • Reformat: A change that MUST be just a formatting path, e.g. change spaces.

  • Rearrange: A change that MUST be just an arranging patch, e.g. change layout.

  • Redraw: A change that MUST be just a drawing patch, e.g. change a graphic, image, icon, etc.

  • Reword: A change that MUST be just a wording patch, e.g. change a comment, label, doc, etc.

  • Revise: A change that MUST be just a revising patch e.g. a change, an alteration, a correction, etc.

  • Refit/Refresh/Renew/Reload: A change that MUST be just a patch e.g. update test data, API keys, etc.

Real-world examples

Real-world examples show how we use imperative mood, present tense, active voice, and verbs:

  • Add feature for a user to like a post

  • Drop feature for a user to like a post

  • Fix association between a user and a post

  • Bump dependency library to current version

  • Make build process use caches for speed

  • Start feature flag for a user to like a post

  • Stop feature flag for a user to like a post

  • Optimize search speed for a user to see posts

  • Document community guidelines for post content

  • Refactor user model to new language syntax

  • Reformat home page text to use more whitespace

  • Rearrange buttons so OK is on the lower right

  • Redraw diagram of how our web app works

  • Reword home page text to be more welcoming

  • Revise link to update it to the new URL

Use semantic versioning

We use semantic versioning for many of our projects:

  • Add, Start: Increment SemVer MINOR version when there is a new capability.

  • Drop, Stop: Increment SemVer MAJOR version when there is an incompatibility.

  • Fix, Bump, Make, Optimize, Document: Increment SemVer PATCH version.

  • Refactor, Reformat, Rearrange, Redraw, Reword: Increment SemVer PATCH version.

Specifics for right and wrong

Capitalize the summary.

  • Right: Add feature

  • Wrong: add feature

Finish the summary without a sentence-ending a period.

  • Right: Add feature

  • Wrong: Add feature.

If the summary ends with an non-sentence-ending period, use it.

  • Right: Add feature for U.S.A.

  • Wrong: Add feature for U.S.A

Use imperative mood: present tense, active voice, and lead verb.

  • Right: Add feature

  • Wrong: Adds feature (this is indicative mood, not imperative mood)

  • Wrong: Added feature (this is past tense, not present tense)

  • Wrong: Adding feature (this lead is a gerund, not a verb)

  • Wrong: Feature added (this is passive voice, not active voice)

Specifics for length

Keep the summary line within 50 characters.

  • The purpose is easy readability.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Use a blank line after the summary line.

  • The purpose is making the commit message parseable by tools.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Use up to 72 characters per line for typical text for word wrap.

  • The purpose is easy readability on typical terminals.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Use as many characters as needed for atypical text, such as URLs, output, formatted messages, etc.

  • The purpose is preserving important formatting.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Reasoning

We primarily care that our team communicates effectively with our shared understanding.

We secondarily like these verbs above because they're easy to read, easy to type, and clear in many cultures.

If you and your team prefer other words, that's fine too; use what works for you.

Reject these formats

We reject git commit message styles that put meta-information into the summary line.

Example:

  • [bug] ...

  • (release) ...

  • #12345 ...

  • docs: ...

  • JIRA-666 #time 1w 2d 4h 30m #comment Task completed ahead of schedule #resolve

We reject the git commit message style of projects such as Angular, Commitizen defaults, etc.

  • Because these use a leading tag that is sometimes a word, sometimes an abbreviation, sometimes a plural noun, etc.

  • Examples are using "feat" for feature, "docs" for document, "perf" for performance improvement, etc.

  • Instead we use "Add" for adding a feature, "Document" for documenting help, "Optimize" for performance improvement, etc.

  • Active verbs are easier to skim, and easier to use for people from other cultures who may be less-comfortable using English.

We reject using a ticket id number in the summary line.

  • Instead, we use fully-qualified URLs in the commit message body.

  • This is because many of our projects use multiple tracking systems, and multiple ways of launching a URL.

  • We want URL tracking to be easy to use by a wide range of systems, scripts, and teams.

We reject using a time tracking syntax in the summary line.

  • Instead, if you want time tracking, put the info in the commit message body.

  • This is because your personal time tracking is irrelevant to most other developers.

  • If you must use time tracking, we recommend the format of ISO 8601 and UTC, such as "YYYY-MM-DDTHH:MM:SSZ"

Optional: use contact email addresses

We sometimes have more than one person working on a commit. For example, we do do pair programming.

To keep track of this, we write a git commit message body that lists each person. We use the person's name and the email address. We use one person per line because this is easy to parse.

Co-authored-by: Alice Adams <[email protected]>
Co-authored-by: Bob Brown <[email protected]>
Co-authored-by: Carol Curtis <[email protected]>

To make this easy, we use a git commit template.

Optional: use task tracking links

We sometimes connect a git commit to a task tracking system or web page that explains more. For example, we use GitHub, Trello, Jira, and many other bug tracking systems and project management software systems.

To keep track of these, we use a git commit message body that lists each URL, one per line, because this is easy to parse.

Example:

Add feature foo

See: https://github.com/user/repo/issues/789
See: https://jira.com/tasks/123
See: https://wikipedia.com/quicksort

If we want to provide link names, then we use Markdown links, such as:

See: [Request for help with sign in](https://github.com/user/repo/issues/789)
See: [Add feature foo](https://jira.com/tasks/123)
See: [Wikipedia Quicksort](https://wikipedia/quicksort)

To make this easy in practice, we use a git template that helps fill in this info.

Optional: use resource tracking metrics

We sometimes connect a git commit to a resource tracking system or metrics scripts. For example, we work on some projects where the project managers must keep track of work hours spent on a commit, or story point estimates per feature branch, or cost of hiring a developer to fix a bug.

To keep track of these, we use a git commit message body that lists each item, one per line, because this is easy to parse.

Example:

Add feature foo

Time: 7 staff hours
Cost: $700
Points: 7

Optional: use keywords, importance, references, etc.

We like to use commit message keywords to help us skim, search, and prioritize.

To keep track of these, we write a git commit message body that uses email header conventions.

Example:

Fix foo

Keywords: security, encryption, authentication
Importance: high
References: ...
Supersedes: ...
Obsoletes: ...
See-Also: ...

We use some of these to help our teams focus on the most important work.

  • When a commit message says "Importance: high" then it gets priority for code review and also for testing on the continuous integration server.

  • When a commit message says "Supersedes", "References", "Obsoletes", then we can easily look up the earlier commits or URLs.

Related links

Blog posts about how to write git commit messages:

Tools that help with git commit messages:

More Repositories

1

architecture-decision-record

Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation
11,128
star
2

queueing-theory

Queueing theory: an introduction for software development
2,078
star
3

monorepo-vs-polyrepo

Monorepo vs. polyrepo: architecture for source code management (SCM) version control systems (VCS)
991
star
4

ways-of-working

Ways of Working (WoW) with team principles, values, tenets, ground rules, aspirations, norms, working agreements, shared expectations, and group understandings
619
star
5

objectives-and-key-results

Objectives and Key Results (OKR) examples for goals, tasks, plans, projects, and strategy.
344
star
6

pitch-deck

Pitch deck advice for startup founders who want to raise venture capital investment
285
star
7

demo-rust-axum

Demo of Rust and axum web framework with Tokio, Tower, Hyper, Serde
Rust
278
star
8

github-special-files-and-paths

GitHub special files and paths, such as README, LICENSE, .github, docs, dependabot, workflows.
192
star
9

stable-diffusion-image-prompt-gallery

Stable Diffusion: image prompt gallery of examples for various prompts
Shell
178
star
10

maturity-models

Maturity models for IT, Agile, DevOps, TOGAF, Six Sigma, P3M3, etc.
172
star
11

plantuml-examples

PlantUML eaxmples for UML, ERD, wireframes, mind maps, JSON, YAML, WBS, ASCII art, Gantt charts, C4 models, and more
168
star
12

git-commit-template

Git commit template for better commit messages
163
star
13

stable-diffusion-macos-install-help

Stable Diffusion: macOS install help with homebrew, python, anaconda, dream, etc.
130
star
14

key-performance-indicator

Key performance indicator (KPI) examples for metrics, measurements, objectives and key results (OKRs)
129
star
15

brewfile

Brewfile
Ruby
111
star
16

crucial-conversations

Crucial conversations: lessons from the worldwide bestseller book
95
star
17

decision-record

Decision record: how to initiate and complete decisions for teams, organizations, and systems
92
star
18

statement-of-work

Statement Of Work (SOW) example
67
star
19

demo-swift-excel-xlsx-reader-writer

Demo Swift Excel Xlsx Reader Writer
Swift
60
star
20

inclusive-language

Inclusive language
57
star
21

strategic-balanced-scorecard

Strategic Balanced Scorecard: planning business by using OKRs, KPIs, and initiatives
49
star
22

issues

Issues: feature requests, bug reports, customer complaints, security alerts, etc.
44
star
23

oblique-strategies

Oblique Strategies: ideas for creative lateral thinking
42
star
24

care-plan

Care plan: a free open source care plan template for caregivers to help with medical, financial, government, legal, and practical care.
41
star
25

startup-superset

Startup superset: summaries of key concepts, ideas, insights
40
star
26

functional-specifications-template

Functional specifications template
40
star
27

always-improving

Book summaries by "alwaysimproving" for business, productivity, life skills, etc.
35
star
28

milestones

Milestones ideas and examples for project management
32
star
29

software-development-methodologies

Software development methodologies: summaries of agile, scrum, DAD, SAFe, etc.
31
star
30

social-network-plan

Social network plan - goals, ideas, step, and tasks for a new site
30
star
31

company-culture

Company culture ideas from Amazon, Netflix, Harvard, Ultimate, etc.
28
star
32

versioning

Versioning: what it is, how to do it, comments and discussion
28
star
33

leadership

Leadership and management ideas
27
star
34

spade-decision-framework

SPADE decision framework: Setting, People, Alternatives, Decide, Explain
27
star
35

system-quality-attributes

Cross-Functional Requirements a.k.a. Quality Attributes
26
star
36

ooda-loop

OODA loop: notes on John Boyd, strategy, tactics, planning, and paradigms
25
star
37

powerful-questions

Powerful questions - catalyzing insight, innovation, action
25
star
38

business-model-canvas

Business model canvas for value propositions, customer relationships, partner collaborations, etc.
25
star
39

thought-leadership-writing

Thought leadership writing tips for content creators, bloggers, authors, and editors
24
star
40

awesome-developing

Awesome developing: ideas for how to create better software code and collaboration
24
star
41

value-stream-mapping

Value Stream Mapping (VSM) tutorial (work in progress)
24
star
42

big-five-personality-traits

Big Five personality traits: domains, aspects, facets
22
star
43

source-code-management

Source code management β†’ notes and ideas β†’ mono-repos, trunk-based-development, etc.
21
star
44

key-risk-indicator

Key risk indicator (KRI) for risk management and business strategy
20
star
45

wordbooks

Demo wordbooks for business, projects, industries, software, consulting, and more
Lua
20
star
46

code-of-conduct-guidelines

Code of Conduct Guidelines
Shell
19
star
47

git-branch-name

Git branch name ideas, naming conventions, and how to use git branch edit description
19
star
48

git-workflow-help

Git flow help: research on Git flow, GitHub flow, GitLab flow, etc.
18
star
49

demo-tailwind-css

Demo Tailwind CSS along with Gulp and PostCSS
JavaScript
18
star
50

functional-specifications-tutorial

Functional specifications tutorial
17
star
51

sha256-sentence

SHA256 sentence: discover a SHA256 checksum that matches a sentence's description of hex digit words.
Rust
17
star
52

team-focus

TEAM FOCUS concepts by Paul N. Friga in McKinsey Engagement.
17
star
53

stakeholder-analysis

Stakeholder analysis for business project management
HTML
17
star
54

smart-criteria

SMART criteria for goals, objectives, plans, etc.
16
star
55

interviewing

Interviewing ideas for hiring managers, job seekers, and recruiting candidates
16
star
56

vision_mission_statements

Vision statements and mission statements by many companies and organizations
16
star
57

goals-ideas-steps-tasks

Goals, Ideas, Steps, Tasks: GIST Planning
14
star
58

icebreaker-questions

Icebreaker questions to help people, groups, teams, meetings, and such
14
star
59

coordinated-disclosure

Coordinated disclosure for security discoveries, bug reports, etc.
13
star
60

outputs-vs-outcomes

Outputs vs. outcomes: what's the different and why does it matter?
12
star
61

discovery-assessment

Discovery assessment for project management
12
star
62

critical-success-factor

Critical Success Factor (CSF) tutorial
12
star
63

software-operations-items

Software operations items
12
star
64

demo-rust-cargo-tdd

Demo of Rust and Cargo for TDD (test driven development)
Rust
11
star
65

agile-assessment

Agile assessment exercise ideas
11
star
66

metrics

Metrics
10
star
67

responsibility-assignment-matrix

Responsibility assignment matrix (RAM) a.k.a. linear responsibility chart (LRC)
10
star
68

social-value-orientation

Social value orientation (SVO) notes for pro-social pro-self concepts
10
star
69

demo-elixir-phoenix

Demonstration of Elixir language and Phoenix framework
Elixir
10
star
70

pgp-gpg-help

Pretty Good Privacy (PGP) GNU Privacy Guard (GPG) help for encryption
9
star
71

causal-analysis-based-on-system-theory

Causal Analysis based on System Theory (CAST)
9
star
72

demo-job-descriptions

Demo job descriptions
9
star
73

demo-terraform-aws

Demo of Terraform by Hasicorp for AWS
HCL
9
star
74

lean-business-lists

Lean business lists
9
star
75

issue-postmortem-template

Issue postmortem template for incident response documentation
8
star
76

net-promoter-score

Net Promoter Score (NPS) introduction and recommendations
8
star
77

initiatives-and-experiments

Initiatives and experiments
8
star
78

demo-rust-cursive

Demo Rust Cursive crate for terminal user interface (TUI)
Rust
8
star
79

demo-swift-rest

Demo Swift REST
HTML
8
star
80

git-hooks

Git hooks
Shell
7
star
81

demo-devops

Demo devops
7
star
82

adkar-change-management-model

ADKAR change management model: awareness, desire, knowledge, ability, reinforcement
7
star
83

demo-optaplanner

Demo OptaPlanner constraint solver
Java
6
star
84

intent-plan

Intent plan for mision, state, sequence, decisions, antigoals, constraints, expressives
6
star
85

demo-rust-rocket

Demo of Rust Rocket web application framework
Rust
6
star
86

task-life-cycle

Task life cycle (TLC)
5
star
87

feedback-request-template

Feedback request template
5
star
88

first-aid-kit

First Aid Kit
5
star
89

inspiring-people

Inspiring people: one hundred living people with short bios thanks to Wikipedia
5
star
90

principles

Principles: summaries of ethical prinicples, leadership principles, teamwork principles, ui/ux design principles, software programming principles, etc.
5
star
91

demo-aws-ses-smtp

Demo of Amazon Web Services (AWS) Simple Email Service (SES) Simple Mail Transfer Protocol (SMTP)
4
star
92

aberystwyth-wales-book

Aberystwth Wales Book - Photos of the Town
Shell
4
star
93

safety-philosophy

Safety philosopy: example principles for an organization and management
4
star
94

demo-shopping-cart-exercise-with-ruby

Shopping cart exercise with Ruby: how to program a shop, cart, till, checkout, etc. with TDD
Ruby
4
star
95

demo-gulp

Demo gulpfile.js using Gulp, PostCSS, Tailwind CSS, Pino, unfold, and more
JavaScript
4
star
96

git-troubleshooting

Git troubleshooting
4
star
97

demo-svelte-hello-world

Demo Svelte JavaScript framework "hello world" app
JavaScript
4
star
98

demo-ansible

Demo Ansible configuration tool for install, update, users, groups, etc.
4
star
99

quad-chart

Quad chart: a rapid project planning summary guide
4
star
100

adventure-gear

Adventure gear for traveling, backpacking, camping, and more
4
star