13 Sending a patch from a git repo

Firstly, if you can set up an accessible remote repo, please do so. You can see how easy it is in section See Setting up a publicly accessible repo. It will make things so much easier for everyone. We do understand that there may be some valid reasons why you can’t, and that is okay, this section still provides a valid workflow.

Before you do anything, we recommend that you run the git-for-steve.sh script which you’ll find in the contrib directory. It will ensure that some basic git config settings are correct, and set up your “for-steve” tracking branch.

Preparing a patch from a git repo

Are you in the right place? You cloned the SXEmacs sources with git clone http://git.sxemacs.org/sxemacs.

Yes? OK, great, read on.

Your workflow should run something along these lines…

1. git pull from your “for-steve” branch to sync up with the main SXEmacs repo.
2. git checkout -b mybugfix to create and checkout a new branch. You can call it whatever you like, just as long as you know what it’s about. (Yeah, we recommend that you do all your work on branches and keep your master branch as pristine as possible).
3. hack hack edit edit fix fix hack
4. Test! If all is good, proceed. If not, return to the previous step.
5. The next step is to commit your changes, and at this point I’d like to note that, although not mandatory, we encourage and prefer it if you sign all of your commits with GnuPG. This can be easily set up via git config commit.gpgSign true¹.

   Depending on how you like to deal with change logs, and if the changes were small and trivial or detailed and large:

   • git commit -sam "Summary of changes" For use with small quick changes that don’t really warrant verbose logs to document them.
   • git commit -sa This form will fire up an editor for you to write your change logs in².
   • git commit -saF mylogfile Use this form for the times when you have logged your changes as you went to the file mylogfile.

   Please take note, that whichever commit command you use, to always use the -s option to add a Signed-off-by entry to the log. This will indicate that you played some role in getting the patch into the code base, and, perhaps more importantly, you had permission to do so³.

   For patches that you’re submitting to the main SXEmacs code base that have originated from somebody else (maybe you have a small team of sub-developers working for you), the Signed-off-by entry also indicates that you have reviewed, tested, and approved the patch. And also, the original author has permission to submit it.

6. git checkout for-steve To flip back to your for-steve branch.
7. git merge mybugfix To merge the changes from the mybugfix branch into your for-steve branch.

   At this point everything that was in the mybugfix branch is now in your for-steve branch, so you no longer need it. You can safely delete it with git branch -d mybugfix.

   Now if you have a publicly accessible repo, you should do:

8. git push myremote for-steve To push the changes to your publicly accessible repo, myremote.

If your repos is private, it is safe to skip the push and just advance to the next step.

Patch Submission

At this point, your changes are ready for Steve to incorporate into the main SXEmacs code base. All you need to do is let him know, and you can easily do that with the following 2 git commands⁴:

1. git format-patch --add-header="X-Git-Repo: REPO-URL" \
--add-header="X-Git-Branch: for-steve" \
--subject-prefix="P-Req" --minimal --numbered -o DIR origin/master
2. git send-email \
--to="SXEmacs Patches <sxemacs-patches@sxemacs.org>" \
--from="$(git config user.name) <$(git config user.email)>" DIR

If you not have have a publicly accessible repository, the SXEmacs developers can’t pull in your changesets directly from you. Instead, once your patch hits the mailing list and is approved, it will have to be applied manually to the SXEmacs code base.

You could, in theory, use a post-commit hook, but I’d not recommend it. Think about the situation where you are working on something fairly big. You’d most likely commit several times before you have things ready for us.

If you have a publicly accessible repo, be sure to setup automation like in See Automation.