git best practices

[Ralf Wildenhues]

I'm writing this in the hope that it will be useful.  Some things are
certainly up for debate, and I don't have a strong opinon on them.

This is not a git tutorial, or a "how to use git effectively with GNU
packages" tutorial.  I believe Jim has written something the latter end
before for coreutils or gnulib, but I've lost the URL.  Jim?


- git gets the most out of commit messages if they consist of a
on-line description of the patch, then a blank line, then the
detailed patch description.  I've gotten used to match a ChangeLog entry

-- snip --
200x-xx-xx  A U Thor  <address@hidden>  (tiny change)

        Fix foo, implement bar.
        * file1 (function1): New.
        * file2: Delete.
        Report by Bu G Reporter.
-- snip --

to a commit message of the form 

-- snip --
Fix foo, implement bar.

* file1 (function1): New.
* file2: Delete.
Report by Bu G Reporter.
-- snip --

with something semi-scripted, but probably well approximated with
  sed '/^2/d; /^$/d; s/^        //; '

and commit it using
  git add $changed_files
  git commit -s --author 'A U Thor <address@hidden>'

(note there's only one space after Thor here).  --author is not needed
for patches written by you, if you've told git about your user name and
address properly.

See <http://git.or.cz/gitwiki/CommitMessageConventions> for why the
message format matters.

If somebody would adjust commit.m4sh to this end, that would be great.


- If we have patches that go on several branches, please try to follow
the convention of applying the patch to master first, then use
cherry-pick to get it into a branch.  This ensures master doesn't regress
wrt. an older branch.  (Do not use merge unless you want to merge all
changes from one branch to another, rather than just the single commit
you mention.)

- We should discuss whether applied patches need to be posted to
libtool-patches, and if yes, whether in some special form.  If you
post several proposed patches, it is helpful to use 'git format-patch'
because then the receiving end can use 'git am' to apply them very
easily and safely.  FYI, for mails formatted with format-patch, the
upstream git community has come to put added comments after the dashes
at the end of the commit message, but before the diffstat (the
"statistics" thingy that shows what files changed and by how much).

- When applying patches to push them, please rebase them against the
current tree; IOW, don't push artificial merge commits that result from
you merging in upstream changes into your tree.  Jim's doc have more
on this, I think.  FWIW, I have this in my ~/.gitconfig:

[branch "master"]
        rebase = true

which arguably proves me to be a person permanently damaged by CVS.  ;-)

Cheers,
Ralf