Skip to main content
This guide covers the patch submission workflow, coding standards, and best practices for contributing to Git.

​
Patch Lifecycle

Understanding how patches flow through the Git project helps you write better contributions:
1

Development

You code your changes without needing pre-authorization. Your patches will be reviewed on the mailing list to assess the merit of the idea, design, and implementation.
2

Submission

Send patches to the mailing list and CC people who may need to know. Your goal is to get help in creating the best solution, not just to convince others.
3

Review and Iteration

Receive comments and suggestions. Respond with “Reply-All” while preparing updated patches. Polish, refine, and re-send.
4

Integration (seen branch)

The maintainer may queue patches to the seen branch for testing. Being in seen does not mean the patch is accepted.
5

Merge to next

When patches reach consensus, they’re included in “What’s cooking” reports marked “Will merge to ‘next’.” This decision is made by the maintainer with reviewer input.
6

Merge to master

After cooking in next for about 7 days without issues, the topic merges to master and waits for the next major release.

​
Choosing a Starting Point

Always base your work on the oldest integration branch that your change is relevant to.
Git has four integration branches:
  • maint - Oldest, for released version fixes
  • master - Current development
  • next - Topics being tested
  • seen - Experimental integration

​
Which Branch to Use

# Base on maint
git checkout -b my-bugfix maint
next and seen are inappropriate starting points. They are frequently re-integrated and force-pushed, making them unsuitable as a base for new work.

​
Making Commits

​
Separate Logical Changes

Make separate commits for logically separate changes. Always make a commit with a complete commit message rather than generating patches between your working tree and commit head.

​
Commit Message Format

Subject Line:
  • Maximum 50 characters (soft limit)
  • Prefix with “area: ” (e.g., doc:, builtin/merge:, refs:)
  • No period at the end
  • First word after prefix is lowercase unless it’s a proper noun
  • Use imperative mood: “make xyzzy do frotz” not “makes” or “made”
Examples: 
doc: clarify distinction between sign-off and pgp-signing
refs: HEAD is also treated as a ref
Body:
  • Explain the problem the change solves
  • Justify why the solution is better
  • Note alternate solutions considered but discarded
  • Use present tense for the current state: “The code does X” not “used to do”
  • Use imperative mood for changes

​
Commit Reference Format

When referencing other commits, use: 
Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) noticed that ...
Generate with: 
git show -s --pretty=reference <commit>

​
Sign-Off Requirement

By making a contribution to this project, I certify that:
  • (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
  • (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license; or
  • (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
  • (d) I understand and agree that this project and the contribution are public and that a record of the contribution is maintained indefinitely.
Add to your commit: 
git commit -s
This adds: 
Signed-off-by: Random J Developer <[email protected]>
Use a known, distinctive identity. Anonymous contributions cannot be accepted. You may use a pseudonym or preferred name as long as it’s identifying and not misleading.

​
Additional Trailers

  • Reported-by: - Credits who found the bug
  • Acked-by: - Someone familiar with the area liked the patch
  • Reviewed-by: - Reviewer completely satisfied after detailed analysis
  • Tested-by: - Person tested the patch successfully
  • Co-authored-by: - Multiple people exchanged drafts
  • Helped-by: - Someone suggested ideas for changes
  • Suggested-by: - Someone suggested the idea

​
Testing

​
Sending Patches

​
Using format-patch and send-email

git format-patch -M origin/master

​
Email Guidelines

  • Do NOT attach patches as MIME attachments
  • Do NOT use quoted-printable encoding
  • Do NOT use format=flowed
  • Do NOT PGP sign your patch
  • Submit patches inline in separate messages
Subject prefix conventions:
  • [PATCH] - Normal patch
  • [PATCH v2], [PATCH v3] - Updated versions
  • [RFC PATCH] - Request for comments, needs discussion

​
Choosing Reviewers

Send to the mailing list with CC to relevant people: 
# Find who to CC using git-contacts
perl contrib/contacts/git-contacts <patch-files>

# Or check who worked on the code
git log -p -- path/to/file
Security issues: Submit privately to [email protected] instead of the public mailing list.

​
Use of AI

The project has strict policies regarding AI-generated content:
  • We will reject anything that looks AI-generated
  • Content that sounds overly formal or bloated will be rejected
  • Content that looks good on surface but makes no sense will be rejected
  • You must understand and be able to explain everything you submit
Recommended AI usage:
  • Use AI to guide you step-by-step in producing a solution yourself
  • Use for debugging assistance
  • Use to check for mistakes or style issues before submission
  • Do NOT copy-paste full AI solutions

​
GitHub CI

Test your changes on Linux, Mac, and Windows:
1

Fork

Fork https://github.com/git/git to your GitHub account
2

Push

Push your branches to your fork
3

Monitor

Check CI results at https://github.com/<your-handle>/git/actions/workflows/main.yml
Red X means tests failed. Click on the failing job to view logs and download test artifacts.

​
Subsystems with Dedicated Maintainers

Some parts have separate repositories: All contributions should still go via the git mailing list.

Build docs developers (and LLMs) love

Get started for freeTalk to us