[0/5] Document 'AUTO_MERGE' and more special refs

Message

John Cai via GitGitGadget April 14, 2023, 5:58 p.m. UTC

This series adds documentation (and completion!) for AUTO_MERGE. In doing so
I noticed that some other special refs where not mentioned in 'gitrevisions'
nor suggested by the completion, so I also tried to improve that.

Since the changes are in the same parts of the same files, I thought it made
more sense to send everything in the same series to avoid conflicts, but I
can send the AUTO_MERGE patches on top of the other ones in a separate
series if that would be preferred.

Here is a breakdown of the patches. First the "other special refs" patches:

 * [PATCH 1/5] revisions.txt: document more special refs
 * [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD

Then a preparatory cleanup for the AUTO_MERGE patches:

 * [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section

Finally the AUTO_MERGE patches:

 * [PATCH 4/5] Documentation: document AUTO_MERGE
 * [PATCH 5/5] completion: complete AUTO_MERGE

Thanks Elijah for this very useful feature! Dscho, I'm CC-ing you since you
opened https://github.com/gitgitgadget/git/issues/1471, I hope that's OK.

Cheers,

Philippe.

Philippe Blain (5):
  revisions.txt: document more special refs
  completion: complete REVERT_HEAD and BISECT_HEAD
  git-merge.txt: modernize word choice in "True merge" section
  Documentation: document AUTO_MERGE
  completion: complete AUTO_MERGE

 Documentation/git-diff.txt             |  8 +++++++-
 Documentation/git-merge.txt            | 11 ++++++++---
 Documentation/revisions.txt            | 15 ++++++++++++--
 Documentation/user-manual.txt          | 27 ++++++++++++++++++++++++++
 contrib/completion/git-completion.bash |  2 +-
 5 files changed, 56 insertions(+), 7 deletions(-)


base-commit: a0f05f684010332ab3a706979d191b9157643f80
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1515%2Fphil-blain%2Fdoc-auto-merge-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1515/phil-blain/doc-auto-merge-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1515

Comments

Junio C Hamano April 14, 2023, 6:34 p.m. UTC | #1

"Philippe Blain via GitGitGadget" <[e-mail]> writes:

> This series adds documentation (and completion!) for AUTO_MERGE.

Nice.  It indeed is one of the hard-to-discover gems.

Victoria Dye April 14, 2023, 7:49 p.m. UTC | #2

Philippe Blain via GitGitGadget wrote:
> Here is a breakdown of the patches. First the "other special refs" patches:
> 
>  * [PATCH 1/5] revisions.txt: document more special refs
>  * [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD
> 
> Then a preparatory cleanup for the AUTO_MERGE patches:
> 
>  * [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section
> 
> Finally the AUTO_MERGE patches:
> 
>  * [PATCH 4/5] Documentation: document AUTO_MERGE
>  * [PATCH 5/5] completion: complete AUTO_MERGE
> 
> Thanks Elijah for this very useful feature! Dscho, I'm CC-ing you since you
> opened https://github.com/gitgitgadget/git/issues/1471, I hope that's OK.
> 
> Cheers,
> 
> Philippe.

The documentation you've added is clear without being too verbose (the
AUTO_MERGE description & example in patch 4 are especially helpful), the
completion changes are a nice quality-of-life improvement, and the patches
are well-organized. Aside from one minor (and entirely optional) suggestion
in patch 1, everything in this series looks great to me. Thank you for
making these changes!

Elijah Newren April 15, 2023, 7:09 a.m. UTC | #3

On Fri, Apr 14, 2023 at 10:58 AM Philippe Blain via GitGitGadget
<[e-mail]> wrote:
>
> This series adds documentation (and completion!) for AUTO_MERGE. In doing so
> I noticed that some other special refs where not mentioned in 'gitrevisions'
> nor suggested by the completion, so I also tried to improve that.
>
> Since the changes are in the same parts of the same files, I thought it made
> more sense to send everything in the same series to avoid conflicts, but I
> can send the AUTO_MERGE patches on top of the other ones in a separate
> series if that would be preferred.
>
> Here is a breakdown of the patches. First the "other special refs" patches:
>
>  * [PATCH 1/5] revisions.txt: document more special refs
>  * [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD
>
> Then a preparatory cleanup for the AUTO_MERGE patches:
>
>  * [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section
>
> Finally the AUTO_MERGE patches:
>
>  * [PATCH 4/5] Documentation: document AUTO_MERGE
>  * [PATCH 5/5] completion: complete AUTO_MERGE
>
> Thanks Elijah for this very useful feature! Dscho, I'm CC-ing you since you
> opened https://github.com/gitgitgadget/git/issues/1471, I hope that's OK.

Sweet, thanks for sending this in.  I like the little touches you
added such as 3/5,
and fixing up docs of other refs.

I found a couple typos and some slightly misleading text in 4/5.

I'm also curious if it'd be worth attempting to point out the link
between AUTO_MERGE and the --remerge-diff flag to `git log` and `git
show`, though even if it is, it could always be added after this
series.

Chris Torek April 16, 2023, 10:26 a.m. UTC | #4

I wonder if it's worth mentioning that these pseudo-refs
are really per-work-tree. A few too many add-ons to Git
forget to take this into consideration...

Chris