Re: Update HACKING

[Bruno Haible]

Paul Eggert wrote:
> > +* Before pushing a commit, it is highly recommended that you review it in
> > +  its entirety. The easiest way to do so is to run
> > +    $ gitk
> 
> I use 'git format-patch' and then read the patch; this works reasonably 
> well for me. gitk is nice, but can be a hassle if I'm in Emacs or logged 
> in remotely.

In fact, I use this method frequently too :) Let's mention it in the HACKING
file (patch below).

> > +* We use a linear git history — no merges. To work in this setting, it's
> > +  recommended that you configure git with 'git config pull.rebase = true'.
> 
> I don't follow this recommendation: instead, I make sure that my master 
> branch matches upstream exactly. That way, my commit IDs are identical 
> to upstream and I don't need to worry about differences between 
> origin/master and master.

?? That's not a difference between how I and how you work. 'git config
pull.rebase = true' precisely enforces that upstream commit IDs and local
commit IDs match. <https://git-scm.com/docs/git-pull> says
  "When true, rebase the current branch on top of the upstream branch
   after fetching."

> On the rare occasions when I find someone else 
> has collided with me in pushing to master, I revert my local changes, 
> pull (without either rebasing or merging), and then reapply my changes 
> before pushing.

I do the same when I have an entire series of patches to push. But for a
single patch, the worst thing that can happen through a 'git pull --rebase'
are a couple of conflict markers.

Since reapplying the patches is generally more time-consuming and also more
risky (e.g. what if one gets interrupted and later removes the 000*-* files
that lie around?), I'm more comfortable with recommending the automatic rebase.

> Also, even if one prefers pull rebasing, 'git config 
> branch.autoSetupRebase always' might be gentler

Does this configuration have an effect on the master branch that is already
checked out? I don't think so. I use 'git config branch.autoSetupRebase always'
in other projects, when working with topic branches, such as for producing
pull requests.

Bruno


2024-04-23  Bruno Haible  <bruno@clisp.org>

        Update HACKING.
        Suggested by Paul Eggert in
        <https://lists.gnu.org/archive/html/bug-gnulib/2024-04/msg00388.html>.
        * HACKING: Mention an alternative to gitk.

diff --git a/HACKING b/HACKING
index 7a23a33982..8ffe5d5f5e 100644
--- a/HACKING
+++ b/HACKING
@@ -18,8 +18,13 @@ Using git
   recommended that you configure git with 'git config pull.rebase = true'.
 
 * Before pushing a commit, it is highly recommended that you review it in
-  its entirety. The easiest way to do so is to run
-    $ gitk
+  its entirety. The easiest ways to do so are
+    * to run
+        $ git format-patch -1
+      and then read the patch in an editor that has syntax-colouring of patch
+      files, or
+    * to run
+        $ gitk
 
 * We update the ChangeLog by hand.  The commit message is usually identical
   to the ChangeLog entry, with the date and author line removed, with