List header files first in a patch with git

When submitting a patch for review we want our readers/reviewers to be able to read it as easily as possible, and when you make changes to code involving some definitions in a header file you definitely want header files to be listed first in the patch, so that the reader can follow the changes to the code logic knowing already the new definitions.

Changing the order of files in a patch can be done very easily using the -Oorderfile option offered by some git commands.

Let's take this trivial example:

#define ME  (1 << 0)
#define YOU (1 << 1)
#define HER (1 << 2)
#include <stdio.h>
#include "dinner.h"

int main(void)
{
	unsigned long guests = ME | YOU;

	printf("Guests List:\n");

	if (guests & ME)
		printf("  Me\n");

	if (guests & YOU)
		printf("  You\n");

	if (guests & HER)
		printf("  Her\n");

	return 0;
}

And spice it up a little bit:

$ git --no-pager diff
diff --git a/dinner.c b/dinner.c
index dd2b75e..03f211b 100644
--- a/dinner.c
+++ b/dinner.c
@@ -3,7 +3,7 @@

 int main(void)
 {
-       unsigned long guests = ME | YOU;
+       unsigned long guests = ALL;

        printf("Guests List:\n");

diff --git a/dinner.h b/dinner.h
index 8d655d6..fa9e4be 100644
--- a/dinner.h
+++ b/dinner.h
@@ -1,3 +1,4 @@
 #define ME  (1 << 0)
 #define YOU (1 << 1)
 #define HER (1 << 2)
+#define ALL (~0uL)

See? In the patch ALL is used before showing its definition, let's fix this.

Create an orderfile:

*.h
*.c

And now use it to have the header file listed first in the diff.

$ git --no-pager diff -Ogit_order.txt
diff --git a/dinner.h b/dinner.h
index 8d655d6..fa9e4be 100644
--- a/dinner.h
+++ b/dinner.h
@@ -1,3 +1,4 @@
 #define ME  (1 << 0)
 #define YOU (1 << 1)
 #define HER (1 << 2)
+#define ALL (~0uL)
diff --git a/dinner.c b/dinner.c
index dd2b75e..03f211b 100644
--- a/dinner.c
+++ b/dinner.c
@@ -3,7 +3,7 @@
 
 int main(void)
 {
-       unsigned long guests = ME | YOU;
+       unsigned long guests = ALL;
 
        printf("Guests List:\n");

The cool thing is that this works with git format-patch too, so we can do

git format-patch -Ogit_order.txt master..my_dev_branch

and we are set.

Note that git add and git commit do not have this option because when you stage and commit changes git doesn't really care about files and the order they are handled, it's just us human who need hints.


CommentsSyndicate content

Thats a neat trick and

Stefan Schmidt's picture

Thats a neat trick and usabilty feature for reviewers I haven't even thought about before. Thanks for posting this

Post new comment

The content of this field is kept private and will not be shown publicly. If you have a Gravatar account associated with the e-mail address you provide, it will be used to display your avatar.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

More information about formatting options

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
b
g
h
N
n
F
Enter the code without spaces.