| Message ID | 66c7e514157f3c8220eb994cea7c4659d5241042.1681495119.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 9760b4df4baf91b41e516f88c26ccbdeb196eb96 |
| Headers | show |
| Series | Document 'AUTO_MERGE' and more special refs | expand |
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Philippe Blain <levraiphilippeblain@gmail.com> > > Some special refs, namely HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and > CHERRY_PICK_HEAD, are mentioned and described in 'gitrevisions', but some > others, namely REBASE_HEAD, REVERT_HEAD, and BISECT_HEAD, are not. > > Add a small description of these special refs. > > Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> > --- > Documentation/revisions.txt | 11 +++++++++-- > 1 file changed, 9 insertions(+), 2 deletions(-) > > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt > index 9aa58052bc7..98b8f89bc8d 100644 > --- a/Documentation/revisions.txt > +++ b/Documentation/revisions.txt > @@ -32,8 +32,8 @@ characters and to avoid word splitting. > first match in the following rules: > > . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually > - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` > - and `CHERRY_PICK_HEAD`); > + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, > + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`); Adding missing ones and enumerating them indeed is good, but I wonder if the readers will be helped if they are exposed to the phrase "pseudoref" here. This is usually useful only for the pseudorefs, i.e. `HEAD`, `FETCH_HEAD`, ..." We have definition of it in the glossary, but it does not have an exhaustive list (and if we want to have an exhausitive list on this page, the glossary definition of pseudoref may want to point at this page). It is an unrelated tangent that shouldn't be added to the documentation (yet), but didn't we have a plan to limit the pseudorefs to those names that end with "_HEAD"? > +`REBASE_HEAD`, during a rebase, records the commit at which the > +operation is currently stopped, either because of conflicts or an `edit` > +command in an interactive rebase. OK. > +`REVERT_HEAD` records the commit which you are reverting when you > +run `git revert`. OK. > +`BISECT_HEAD` records the current commit to be tested when you > +run `git bisect --no-checkout`. OK. Looking very good.
Philippe Blain via GitGitGadget wrote: > @@ -55,8 +55,15 @@ you can easily change the tip of the branch back to the state before you ran > them. > `MERGE_HEAD` records the commit(s) which you are merging into your branch > when you run `git merge`. > +`REBASE_HEAD`, during a rebase, records the commit at which the > +operation is currently stopped, either because of conflicts or an `edit` > +command in an interactive rebase. > +`REVERT_HEAD` records the commit which you are reverting when you > +run `git revert`. > `CHERRY_PICK_HEAD` records the commit which you are cherry-picking > when you run `git cherry-pick`. > +`BISECT_HEAD` records the current commit to be tested when you > +run `git bisect --no-checkout`. This is a fairly minor point, so feel free to ignore if you disagree or feel it's not worth the effort: Although the special refs in this list (HEAD, MERGE_HEAD, REBASE_HEAD etc.) are visually separated by newlines in this doc, they render in the manpages & HTML in a single monolithic paragraph (see [1]). With the addition of three more descriptions (four if you count 'AUTO_MERGE' in patch 4/5), that paragraph is getting large enough that it might be difficult for a reader to parse and find information about a specific ref. To help with that, you could create visual separation in the rendered doc by adding a '+' between each special ref description; converting them into a bullet pointed list would also work, I think. [1] https://git-scm.com/docs/revisions#Documentation/revisions.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem > + > Note that any of the 'refs/*' cases above may come either from > the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
On Fri, Apr 14, 2023 at 12:49:16PM -0700, Victoria Dye wrote: > To help with that, you could create visual separation in the rendered doc by > adding a '+' between each special ref description; converting them into a > bullet pointed list would also work, I think. In case you're looking for another option, you could convert these into a description list, which would be consistent with the outer-most list in this document. I had to refresh myself on how the spacing and continuations work in ASCIIdoc, but I think the following (which applies on top of this patch) is right: --- 8< --- diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 98b8f89bc8..b34f981622 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -30,7 +30,7 @@ characters and to avoid word splitting. explicitly say 'heads/master' to tell Git which one you mean. When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: - ++ . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`); @@ -44,26 +44,34 @@ characters and to avoid word splitting. . otherwise, 'refs/remotes/<refname>' if it exists; . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + + -`HEAD` names the commit on which you based the changes in the working tree. -`FETCH_HEAD` records the branch which you fetched from a remote repository -with your last `git fetch` invocation. -`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic -way (`git am`, `git merge`, `git rebase`, `git reset`), -to record the position of the `HEAD` before their operation, so that -you can easily change the tip of the branch back to the state before you ran -them. -`MERGE_HEAD` records the commit(s) which you are merging into your branch -when you run `git merge`. -`REBASE_HEAD`, during a rebase, records the commit at which the -operation is currently stopped, either because of conflicts or an `edit` -command in an interactive rebase. -`REVERT_HEAD` records the commit which you are reverting when you -run `git revert`. -`CHERRY_PICK_HEAD` records the commit which you are cherry-picking -when you run `git cherry-pick`. -`BISECT_HEAD` records the current commit to be tested when you -run `git bisect --no-checkout`. + `HEAD`::: + names the commit on which you based the changes in the working tree. + `FETCH_HEAD`::: + records the branch which you fetched from a remote repository with + your last `git fetch` invocation. + `ORIG_HEAD`::: + is created by commands that move your `HEAD` in a drastic way (`git + am`, `git merge`, `git rebase`, `git reset`), to record the position + of the `HEAD` before their operation, so that you can easily change + the tip of the branch back to the state before you ran them. + `MERGE_HEAD`::: + records the commit(s) which you are merging into your branch when you + run `git merge`. + `REBASE_HEAD`::: + during a rebase, records the commit at which the operation is + currently stopped, either because of conflicts or an `edit` command in + an interactive rebase. + `REVERT_HEAD`::: + records the commit which you are reverting when you run `git revert`. + `CHERRY_PICK_HEAD`::: + records the commit which you are cherry-picking when you run `git + cherry-pick`. + `BISECT_HEAD`::: + records the current commit to be tested when you run `git bisect + --no-checkout`. + + Note that any of the 'refs/*' cases above may come either from the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. --- >8 --- Thanks, Taylor
Junio C Hamano wrote: > "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes: > > > From: Philippe Blain <levraiphilippeblain@gmail.com> > > > > Some special refs, namely HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and > > CHERRY_PICK_HEAD, are mentioned and described in 'gitrevisions', but some > > others, namely REBASE_HEAD, REVERT_HEAD, and BISECT_HEAD, are not. > > > > Add a small description of these special refs. > > > > Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> > > --- > > Documentation/revisions.txt | 11 +++++++++-- > > 1 file changed, 9 insertions(+), 2 deletions(-) > > > > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt > > index 9aa58052bc7..98b8f89bc8d 100644 > > --- a/Documentation/revisions.txt > > +++ b/Documentation/revisions.txt > > @@ -32,8 +32,8 @@ characters and to avoid word splitting. > > first match in the following rules: > > > > . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually > > - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` > > - and `CHERRY_PICK_HEAD`); > > + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, > > + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`); > > Adding missing ones and enumerating them indeed is good, but I > wonder if the readers will be helped if they are exposed to the > phrase "pseudoref" here. First time I've heard that term. > This is usually useful only for the pseudorefs, i.e. `HEAD`, > `FETCH_HEAD`, ..." Isn't `HEAD` supposed to be a "symbolic ref"? It definitely seems some explanation is missing.
Taylor Blau wrote: > On Fri, Apr 14, 2023 at 12:49:16PM -0700, Victoria Dye wrote: > > To help with that, you could create visual separation in the rendered doc by > > adding a '+' between each special ref description; converting them into a > > bullet pointed list would also work, I think. > > In case you're looking for another option, you could convert these into > a description list, which would be consistent with the outer-most list > in this document. > > I had to refresh myself on how the spacing and continuations work in > ASCIIdoc, but I think the following (which applies on top of this patch) > is right: Fortunately it's easy to test: asciidoctor - <<\EOF >foo.html `HEAD`::: names the commit on which you based the changes in the working tree. `FETCH_HEAD`::: records the branch which you fetched from a remote repository with your last `git fetch` invocation. EOF Yes, the format is fine, I'd just use `::` instead of `:::` as that's generally the first level, but in practical terms doesn't really matter. https://docs.asciidoctor.org/asciidoc/latest/lists/description/ Cheers.
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 9aa58052bc7..98b8f89bc8d 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -32,8 +32,8 @@ characters and to avoid word splitting. first match in the following rules: . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` - and `CHERRY_PICK_HEAD`); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`); . otherwise, 'refs/<refname>' if it exists; @@ -55,8 +55,15 @@ you can easily change the tip of the branch back to the state before you ran them. `MERGE_HEAD` records the commit(s) which you are merging into your branch when you run `git merge`. +`REBASE_HEAD`, during a rebase, records the commit at which the +operation is currently stopped, either because of conflicts or an `edit` +command in an interactive rebase. +`REVERT_HEAD` records the commit which you are reverting when you +run `git revert`. `CHERRY_PICK_HEAD` records the commit which you are cherry-picking when you run `git cherry-pick`. +`BISECT_HEAD` records the current commit to be tested when you +run `git bisect --no-checkout`. + Note that any of the 'refs/*' cases above may come either from the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.