Before you start contributing to git, you'll need to have a good understanding of a couple of important topics. I've listed some resources below that I found useful.
- Git Coding Guidelines
- Submitting Patches
- How to maintain Git
- Git Build and Installation
- Git Test Harness Usage and API
- git-format-patch Documentation
- git-send-email Documentation
I found this very helpful, because I could go see how people format their emails and patches. Here is how to join.
Git hosts a source code mirror on GitHub, which is the easiest way to get a copy of the code. Just clone it from there. You can also clone or browse the repository from Kernel.org git repositories.
I personally use CLion for an IDE, but you can use whatever you'd like. Be sure to configure your IDE to use tabs instead of spaces.
If you're using CLion, you'll often find yourself stepping over the .idea directory. To get around this, you can edit .git/info/exclude and add the following line. This is similar to adding to the project .gitignore, but only applies to your local environment.
.idea
First, you should (almost) always base your changes off of the maint branch. Read Submitting Patches for more details on this.
Checkout a branch and start making your changes.
Once you have a chunk of work ready, it's time to commit. Heres how you do it:
git add <your changes>
git commit --no-gpg-sign --signoff
Then your commit message should look something like this example:
commit-tree: add missing --gpg-sign flag
Add --gpg-sign option in commit-tree, which was documented, but not
implemented, in 55ca3f99ae. Add tests for the --gpg-sign option.
Signed-off-by: Brandon Richardson <[email protected]>
The first line of the commit message should be short and succinct, as it will become the email subject title. Here's where it becomes useful to look at other emails on the mailinglist to get some inspiration. Also note that you should NOT gpg sign your commits.
This step is not mandatory, but useful if you need to attach more information to your patch that will help reviewers understand your changes (information that wouldn't go directly in your commit message).
Notes are created using git notes add, and will default to reference the most recent commit (HEAD).
Once you create your note, you will embed it into your patch. See Creating patches for details.
To generate email-friendly patches, use git format-patch. Here is an example:
git format-patch -1 --subject-prefix="PATCH" -o <output dir>
The above command will create a single (-1) patch from the lastest commit on the current branch. The --subject-prefix=[<subject>] is optional here, because it will be "PATCH" by default.
If your patch should consist of more than one commit, use -<n> rather than -1.
If your patch has already been reviewed and you addressed some reviewer feedback, the subject of your next iteration should be "PATCH v2".
To attach a note:
git format-patch -1 --notes
See Creating Notes above.
Patches are sent to the mailinglist through the git send-email tool. These steps will vary depending on what email service you use, so you should read the git-send-email documentation. Here are the steps to send your patches using your gmail account.
First you'll need to update your .gitconfig:
[sendemail]
smtpEncryption = tls
smtpServer = smtp.gmail.com
smtpUser = <email>@gmail.com
smtpServerPort = 587
Then, you'll need to configure your Google account to allow Less secure app access.
Next, send the email. Don't worry, you'll be prompted to accept before the email is actually sent. If you're paranoid (like me), use the --dry-run option.
git send-email changes.patch
If this is a second iteration of your changes, and you used --subject="PATCH v2", you should also send the email to your reviewers. For example:
git send-email [email protected] [email protected],[email protected] changes.patch
If you have multiple commits, you should send your patches as a series. This is easily done by using a pattern, rather than a specific patch:
git send-email /Users/brandon/dev/patches/git/bugfix/v2/000*
To send a (v1) patch:
<make changes>
git add <changes>
git commit --no-gpg-sign --signoff
git format-patch -1
git send-email [email protected] <patch file>
To send a (v2) patch with notes:
<make changes>
git add <changes>
git commit --no-gpg-sign --signoff
git notes add
git format-patch -1 --subject-prefix="PATCH v2" --notes
git send-email [email protected] [(--cc=<reviewer email>)...] <patch file>
To send a (v3) patch series with notes:
<make changes>
git add <changes>
git commit --no-gpg-sign --signoff
git notes add
<make changes>
git add <changes>
git commit --no-gpg-sign --signoff
git notes add
git format-patch -2 --subject-prefix="PATCH v3" --notes
git send-email [email protected] [(--cc=<reviewer email>)...] <patch file>