Sunday, December 5 2010
So, you prepared a bug fix for your favourite piece of software, you're sure that it fixes all problems (also future problems!!) you've ever had and, of course, it's a perfect piece of code. But after sending the perfect patch to relevant discussion list you received something like that:
The patch seems to be OK. Can you remove trailing spaces, fix formatting, submit the patch in git format and add signed-off-by?
After reading it for the third time you knew that you had to learn more about how git works and why trailing spaces are bad.. I had the same problem some time ago. There are quite a few howtos, quick starts and tutorials for git, but nonetheless some information is hard to find, especially if you're not sure what you're looking for.
Let's start with "trailing spaces". If you're using a normal editor you might not even notice that there are some "trailing spaces" in your code. And at the end of the day, tha patch works, so why bother? A short example:
przemo@pldmachine /tmp$ touch test
przemo@pldmachine /tmp$ touch "test "
przemo@pldmachine /tmp$ ls -l
r 1 przemo users 0 12-05 01:17 test
r 1 przemo users 0 12-05 01:17 test
How do you like having 2 "identical" files in the same directory? The same thing can happen in your code - trailing spaces can give false positives when comparing two files. Another example:
przemo@pldmachine /tmp$ diff -Nru test1 test2
--- test1 2010-12-05 14:20:11.282835872 +0000
+++ test2 2010-12-05 14:18:48.271759248 +0000
-1 +1 @@
-This is a line of comment
+This is a line of comment
Are those 2 lines the same or they are different? "Trailinig spaces" are bad!
A next issue is code formatting. On some projects there are very loose rules, on some, like linux kernel, rules are the strict. Anyway you shoud always know what are the rules for the project you're working on and adhere to them. If in doubt - ask. If you're not sure why code formatting is an important thing, try to find something in a piece of badly formatted php code - it's very, very hard.
The last part of the fix-your-code email was request for a git formatted patch. I presume you already have a git repository withthe project (git clone path-to-the-project) and you made the modifications to the code. A next step is to commit your modifications to the git repository:
git commit -a
"-a" switch tells git that you want to include all modified files to the repo. After issuing that command you'll see an editor window with some information about the changes you made. git is expecting you to type name for the commit in first line of the editor (a short description what your patch is). The second line should be empty and starting from 3rd line you should give detailed description how your patch works. The title of the patch and it's description may seem to be a silly idea for beginners - my patch works, I know how it works, so simple "Fix that annoying bug" comment should do. Let me say that I can bet that in six month time you will not know what was the bug, how the code works and if it was required at all! Another thing is that you're not working alone - the patch you made should be easy to read and to understand for the person responsible for the project. You should not expect that he or she is going to analyse your code without good explanation.
Now the "signed-off-by". It's meaning can be different for different projects, but in generel it maens that the patch is complete, ready for review and that you agree to use it in the project. Adding "signed-off-by" is very easy. "-s" option does it for you:
git commit -a -s
If you already commited you changes to the repo you can use "--amend" option:
git commit --amend -s
This time git opens editor window, with your previous title of the patch and the description, but there is one new thing - below the last line of the description git adds an empty line and somethinglike this:
Signed-off-by: John Doe <firstname.lastname@example.org>
Now we have the patch commited, with proper title, description and signed-off-by line. We want git to save the patch as a file:
git format-patch HEAD~1
HEAD~1 part means the we want to generate patch for HEAD (it's the current state of the repo) minus one commit. You can also use
HEAD~5 to generate more that just one patch. If you open the file that git just created and you'll see that it contains all the required information: title, description, signed-off-by and all the changes you made to the code.