git format-patch is your Friend
Warning: This post is over a year old. I don't always update old posts with new information, so some of this information may be out of date.
An explanation of the "git format-patch" command, and how it could be used in Drupal's Git workflow.
As an active contributor to the Drupal project, I spend a lot of time working with other peoples’ modules and themes, and occassionally have to fix a bug or add some new functionality.
In the Drupal community, we use a patch based workflow where any changes that I make get exported to a file detailing the differences. The patch file (*.patch) is attached to an item in an issue queue on Drupal.org, applied by the maintainer to their local copy of the code and reviewed, and hopefully committed.
There is an option that the maintainer can add to the end of their commit message.
This differs slightly different for each Drupal user, and the code can be found on their Drupal.org profile page.
If this is added to the end of the commit message, the resulting commit will show that it was committed by the maintainer but authored by a different user. This will then display on Drupal.org that you’ve made a commit to that project.
The problem is that some project maintainers either don’t know about this option or occasionally forget to add it. Dreditor can suggest a commit message and assign an author, but it is optional and, of course, not all maintainers use Dreditor (although they probably should).
git format-patch command seems to be the answer, and will be my preferred method for generating patch files in the future rather than
What does it do Differently?
From the manual page:
Prepare each commit with its patch in one file per commit, formatted to resemble UNIX mailbox format. The output of this command is convenient for e-mail submission or for use with git am.
Here is a section of a patch that I created for the Metatag module using
From 80c8fa14de7f4a83c2e70367aab0aedcadf4f3b0 Mon Sep 17 00:00:00 2001 From: Oliver Davies <firstname.lastname@example.org> Subject: [PATCH] Exclude comment entities when checking if this is the page, otherwise comment_fragment.module will break metatag ---
As mentioned above, the patch is structured in an email format. The commit message is used as the subject line, and the date that the commit was made locally is used for the date. What we’re interested in is the “From” value. This contains your name and email address from your
~/.gitconfig file and is used to author the patch automatically.
Everything below this is the same as a standard patch file, the same as if was generated with
The full patch file can be found at https://drupal.org/files/issues/metatag-comment-fragment-conflict-2265447-4.patch.
How did I create this patch? Here are the steps that I took:
- Clone the source repository using
$ git clone --branch 7.x-1.x http://git.drupal.org/project/metatag.gitand move into that directory.
- Create a branch for this patch using
$ git checkout -b 2265447-comment-fragment-conflict.
- Add and commit any changes as normal.
- Generate the patch file using
$ git format-patch 7.x-1.x --stdout > metatag-comment-fragment-conflict-2265447-4.patch.
Note: I am defining 7.x-1.x in the last step as the original branch to compare (i.e. the original branch that we forked to make our issue branch). This will change depending on the project that you are patching, and it’s version number. Also, commits should always be made against the development branch and not the stable release.
By default, a separate patch file will be created for each commit that we’ve made. This is overridden by the
--stdout option which combines all of the patches into a single file. This is the recommended approach when uploading to Drupal.org.
The resulting patch file can be uploaded onto a Drupal.org issue queue, reviewed by the Testbot and applied by a module maintainer, and you automatically get the commit attributed. Problem solved.
Committing the Patch
If you need to commit a patch that was created using
git format-patch, the best command to do this with is the
git am command.
For example, within your repository, run:
$ git am /path/to/file $ git am ~/Code/metatag-comment-fragment-conflict-2265447-4.patch
You should end up with some output similar to the following:
Applying: #2272799 Added supporters section Applying: #2272799 Added navigation tabs Applying: #2272799 Fixed indentation Applying: #2272799 Replaced URL
Each line is the commit message associated with that patch.
Assuming that there are no errors, you can go ahead and push your updated code into your remote repository.
About the Author
Oliver Davies is a Full Stack Web Developer and System Administrator based in the UK. He is a Senior Software Engineer at Inviqa and a part-time freelancer specialising in Drupal, Symfony and Laravel development and Linux systems administration.