* [PATCH 1/5] git.txt: HEAD is not that special
From: Junio C Hamano @ 2023-12-15 20:32 UTC (permalink / raw)
To: git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com>
The introductory text in "git help git" that describes HEAD called
it "a special ref". It is special compared to the more regular refs
like refs/heads/master and refs/tags/v1.0.0, but not that special,
unlike truly special ones like FETCH_HEAD.
Rewrite a few sentences to also introduce the distinction between a
regular ref that contain the object name and a symbolic ref that
contain the name of another ref. Update the description of HEAD
that point at the current branch to use the more correct term, a
"symbolic ref".
This was found as part of auditing the documentation and in-code
comments for uses of "special ref" that refer merely a "pseudo ref".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/git.txt | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 2535a30194..880cdc5d7f 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for
efficiency may later be compressed together into "pack files".
Named pointers called refs mark interesting points in history. A ref
-may contain the SHA-1 name of an object or the name of another ref. Refs
-with names beginning `ref/head/` contain the SHA-1 name of the most
+may contain the SHA-1 name of an object or the name of another ref (the
+latter is called a "symbolic ref").
+Refs with names beginning `ref/head/` contain the SHA-1 name of the most
recent commit (or "head") of a branch under development. SHA-1 names of
-tags of interest are stored under `ref/tags/`. A special ref named
+tags of interest are stored under `ref/tags/`. A symbolic ref named
`HEAD` contains the name of the currently checked-out branch.
The index file is initialized with a list of all paths and, for each
--
2.43.0-76-g1a87c842ec
^ permalink raw reply related
* [PATCH 3/5] refs.h: HEAD is not that special
From: Junio C Hamano @ 2023-12-15 20:32 UTC (permalink / raw)
To: git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com>
In-code comment explains pseudorefs but used a wrong nomenclature
"special ref".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
refs.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/refs.h b/refs.h
index 23211a5ea1..ff113bb12a 100644
--- a/refs.h
+++ b/refs.h
@@ -56,7 +56,7 @@ struct worktree;
* Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/
* directory and do not consist of all caps and underscores cannot be
* resolved. The function returns NULL for such ref names.
- * Caps and underscores refers to the special refs, such as HEAD,
+ * Caps and underscores refers to the pseudorefs, such as HEAD,
* FETCH_HEAD and friends, that all live outside of the refs/ directory.
*/
#define RESOLVE_REF_READING 0x01
--
2.43.0-76-g1a87c842ec
^ permalink raw reply related
* [PATCH 4/5] docs: AUTO_MERGE is not that special
From: Junio C Hamano @ 2023-12-15 20:32 UTC (permalink / raw)
To: git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com>
A handful of manual pages called AUTO_MERGE a "special ref", but
there is nothing special about it. It merely is yet another
pseudoref.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/git-diff.txt | 2 +-
Documentation/git-merge.txt | 2 +-
Documentation/user-manual.txt | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 08087ffad5..c065f023ec 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -103,7 +103,7 @@ Just in case you are doing something exotic, it should be
noted that all of the <commit> in the above description, except
in the `--merge-base` case and in the last two forms that use `..`
notations, can be any <tree>. A tree of interest is the one pointed to
-by the special ref `AUTO_MERGE`, which is written by the 'ort' merge
+by the ref named `AUTO_MERGE`, which is written by the 'ort' merge
strategy upon hitting merge conflicts (see linkgit:git-merge[1]).
Comparing the working tree with `AUTO_MERGE` shows changes you've made
so far to resolve textual conflicts (see the examples below).
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e8ab340319..3e9557a44b 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -196,7 +196,7 @@ happens:
can inspect the stages with `git ls-files -u`). The working
tree files contain the result of the merge operation; i.e. 3-way
merge results with familiar conflict markers `<<<` `===` `>>>`.
-5. A special ref `AUTO_MERGE` is written, pointing to a tree
+5. A ref named `AUTO_MERGE` is written, pointing to a tree
corresponding to the current content of the working tree (including
conflict markers for textual conflicts). Note that this ref is only
written when the 'ort' merge strategy is used (the default).
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d8dbe6b56d..5d32ff2384 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1344,7 +1344,7 @@ $ git diff --theirs file.txt # same as the above.
-------------------------------------------------
When using the 'ort' merge strategy (the default), before updating the working
-tree with the result of the merge, Git writes a special ref named AUTO_MERGE
+tree with the result of the merge, Git writes a ref named AUTO_MERGE
reflecting the state of the tree it is about to write. Conflicted paths with
textual conflicts that could not be automatically merged are written to this
tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be
--
2.43.0-76-g1a87c842ec
^ permalink raw reply related
* [PATCH 5/5] docs: MERGE_AUTOSTASH is not that special
From: Junio C Hamano @ 2023-12-15 20:32 UTC (permalink / raw)
To: git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com>
A handful of manual pages called MERGE_AUTOSTASH a "special ref",
but there is nothing special about it. It merely is yet another
pseudoref.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/merge-options.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index d8f7cd7ca0..3eaefc4e94 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -191,7 +191,7 @@ endif::git-pull[]
--autostash::
--no-autostash::
Automatically create a temporary stash entry before the operation
- begins, record it in the special ref `MERGE_AUTOSTASH`
+ begins, record it in the ref `MERGE_AUTOSTASH`
and apply it after the operation ends. This means
that you can run the operation on a dirty worktree. However, use
with care: the final stash application after a successful
--
2.43.0-76-g1a87c842ec
^ permalink raw reply related
* [PATCH] git-add.txt: add missing short option -A to synopsis
From: Eric Sunshine @ 2023-12-15 20:43 UTC (permalink / raw)
To: git; +Cc: Benjamin Lehmann, Eric Sunshine
In-Reply-To: <CAM=w4Pn46nTcWA1e=n4Rms76gCx7iqbRmOWf3=vRmKgtbhqQmA@mail.gmail.com>
From: Eric Sunshine <sunshine@sunshineco.com>
With one exception, the synopsis for `git add` consistently lists the
short counterpart alongside the long-form of each option (for instance,
"[--edit | -e]"). The exception is that -A is not mentioned alongside
--all. Fix this inconsistency
Reported-by: Benjamin Lehmann <ben.lehmann@gmail.com>
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
An alternative would be to collapse the synopsis to:
'git add' <options> [--] [<pathspec>...]
as has been done for other command documentation, however doing so would
throw away at-a-glance clues about which options are mutually exclusive,
so adding the missing -A to the synopsis seems preferable (for now, at
least).
Documentation/git-add.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index ed44c1cb31..3d2e670716 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
- [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--sparse]
+ [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
[--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]
--
2.43.0
^ permalink raw reply related
* Re: Bug | Documentation | git add -all | Synopsis has minor mistake
From: Eric Sunshine @ 2023-12-15 20:49 UTC (permalink / raw)
To: Benjamin Lehmann; +Cc: git
In-Reply-To: <CAM=w4Pn46nTcWA1e=n4Rms76gCx7iqbRmOWf3=vRmKgtbhqQmA@mail.gmail.com>
On Fri, Dec 15, 2023 at 7:38 AM Benjamin Lehmann <ben.lehmann@gmail.com> wrote:
> The mistake can be found in the synopsis here:
> https://git-scm.com/docs/git-add#Documentation/git-add.txt--A
>
> In the synopsys, the options -all currently reads:
>
> [--[no-]all | --[no-]ignore-removal |
>
> You can see that there is no mention of -A, which is the main way that
> people would use -all perhaps, so it really ought to be included
> correctly in the synopsis.
This seems to be a simple oversight when the --all option was added by
da98053aa6 (git-add --all: documentation, 2008-07-19).
> In addition, the closing square-bracket is missing.
I think this is inaccurate. If you look closely, you will find the
closing bracket after the -u option:
[--[no-]all | --[no-]ignore-removal | [--update | -u]]
meaning that --all, --ignore-removal, and --update are mutually exclusive.
> Hope this was the right place to report this - seemed to be the only option.
This is the correct place. I posted a patch[1] addressing the issue.
[1]: https://lore.kernel.org/git/20231215204333.1253-1-ericsunshine@charter.net/
^ permalink raw reply
* Re: [PATCH] git-add.txt: add missing short option -A to synopsis
From: Junio C Hamano @ 2023-12-15 21:01 UTC (permalink / raw)
To: Eric Sunshine; +Cc: git, Benjamin Lehmann, Eric Sunshine
In-Reply-To: <20231215204333.1253-1-ericsunshine@charter.net>
Eric Sunshine <ericsunshine@charter.net> writes:
> From: Eric Sunshine <sunshine@sunshineco.com>
>
> With one exception, the synopsis for `git add` consistently lists the
> short counterpart alongside the long-form of each option (for instance,
> "[--edit | -e]"). The exception is that -A is not mentioned alongside
> --all. Fix this inconsistency
>
> Reported-by: Benjamin Lehmann <ben.lehmann@gmail.com>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---
Thanks.
I dug the history just in case we deliberately wanted to leave this
out of the synopsis section, but the side branch leading to the
merge at 378335b3 (Merge branch 'jc/add-addremove', 2008-07-20) does
not say we wanted to discourage "-A" (and encourage "--all"). This
would be a welcome change.
Will queue.
^ permalink raw reply
* Re: [PATCH] git-add.txt: add missing short option -A to synopsis
From: Eric Sunshine @ 2023-12-15 21:04 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Eric Sunshine, git, Benjamin Lehmann
In-Reply-To: <xmqqjzpfkwnr.fsf@gitster.g>
On Fri, Dec 15, 2023 at 4:01 PM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <ericsunshine@charter.net> writes:
> > With one exception, the synopsis for `git add` consistently lists the
> > short counterpart alongside the long-form of each option (for instance,
> > "[--edit | -e]"). The exception is that -A is not mentioned alongside
> > --all. Fix this inconsistency
>
> I dug the history just in case we deliberately wanted to leave this
> out of the synopsis section, but the side branch leading to the
> merge at 378335b3 (Merge branch 'jc/add-addremove', 2008-07-20) does
> not say we wanted to discourage "-A" (and encourage "--all"). This
> would be a welcome change.
I also dug through the history for the same reason and, like you, did
not find any indication that -A was omitted from the synopsis
deliberately. I probably should have stated as much in the patch
commentary.
^ permalink raw reply
* Re: [PATCH 0/5] make room for "special ref"
From: Junio C Hamano @ 2023-12-15 21:21 UTC (permalink / raw)
To: git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com>
Junio C Hamano <gitster@pobox.com> writes:
> ... For example, FETCH_HEAD currently stores not
> just a single object name, but can and is used to store multiple
> object names, each with annotations to record where they came from.
> There indeed may be a need to introduce a new term to refer to such
> "special refs".
The "may be" here vaguely hints another possibility. If we manage
to get rid of the "special refs", we do not even have to mention
"special refs", and more importantly, we do not need extra code to
deal with them.
For FETCH_HEAD, for example, I wonder if an update along this line
is possible:
* Teach "git fetch" to store what it writes to FETCH_HEAD to a
different file, under a distinctly different filename (e.g.,
$GIT_DIR/fetched-tips). Demote FETCH_HEAD to a pseudoref, and
store the first object name in that "fetched-tips" file to it.
* Teach "git pull" to learn what it used to learn from FETCH_HEAD
(i.e., list of fetched tips, each annotated with what ref at what
repository it came from and if it is to be merged) from the new
"fetched-tips" file.
The "special" ness of FETCH_HEAD is really an implementation detail
of how "git pull" works and how the findings of "git fetch" are
communicated to "git pull". The general refs API should not have to
worry about it, and the refs backends should not have to worry about
storing more than just an object name (or if it is a symbolic ref,
the target refname).
An end-user command like "git log ORIG_HEAD..FETCH_HEAD" would not
be affected by changes along the above line, because the current
FETCH_HEAD, when used as a revision, will work as if it stores the
single object name that is listed first in the file.
If somebody is reading FETCH_HEAD and acting on its contents (rather
than merely consuming it as a ref of the first object), perhaps
feeding it to "git fmt-merge-msg", they will be broken by such a
change (indeed, our own "git pull" will be broken by the change to
"git fetch", and the second bullet point above is about fixing the
exact fallout from it), but I am not sure if that is a use case worth
worrying about.
Hmm?
^ permalink raw reply
* Re: [PATCH 1/5] git.txt: HEAD is not that special
From: Ramsay Jones @ 2023-12-15 21:57 UTC (permalink / raw)
To: Junio C Hamano, git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-2-gitster@pobox.com>
On 15/12/2023 20:32, Junio C Hamano wrote:
> The introductory text in "git help git" that describes HEAD called
> it "a special ref". It is special compared to the more regular refs
> like refs/heads/master and refs/tags/v1.0.0, but not that special,
> unlike truly special ones like FETCH_HEAD.
>
> Rewrite a few sentences to also introduce the distinction between a
> regular ref that contain the object name and a symbolic ref that
> contain the name of another ref. Update the description of HEAD
> that point at the current branch to use the more correct term, a
> "symbolic ref".
>
> This was found as part of auditing the documentation and in-code
> comments for uses of "special ref" that refer merely a "pseudo ref".
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/git.txt | 7 ++++---
> 1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 2535a30194..880cdc5d7f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for
> efficiency may later be compressed together into "pack files".
>
> Named pointers called refs mark interesting points in history. A ref
> -may contain the SHA-1 name of an object or the name of another ref. Refs
> -with names beginning `ref/head/` contain the SHA-1 name of the most
> +may contain the SHA-1 name of an object or the name of another ref (the
> +latter is called a "symbolic ref").
> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
Hmm, s:ref/head:refs/heads: right?
> recent commit (or "head") of a branch under development. SHA-1 names of
> -tags of interest are stored under `ref/tags/`. A special ref named
> +tags of interest are stored under `ref/tags/`. A symbolic ref named
> `HEAD` contains the name of the currently checked-out branch.
>
> The index file is initialized with a list of all paths and, for each
^ permalink raw reply
* Re: [PATCH 1/5] git.txt: HEAD is not that special
From: Junio C Hamano @ 2023-12-15 22:06 UTC (permalink / raw)
To: Ramsay Jones; +Cc: git, Patrick Steinhardt
In-Reply-To: <0c93d426-17c3-434c-bbd0-866c31c23f9d@ramsayjones.plus.com>
Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
>> -may contain the SHA-1 name of an object or the name of another ref. Refs
>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>> +may contain the SHA-1 name of an object or the name of another ref (the
>> +latter is called a "symbolic ref").
>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>
> Hmm, s:ref/head:refs/heads: right?
Yeah, right, not a new problem with this change, but is indeed a
good thing to catch and correct. Thanks for a careful review.
^ permalink raw reply
* Re: [PATCH 1/5] git.txt: HEAD is not that special
From: Junio C Hamano @ 2023-12-15 22:19 UTC (permalink / raw)
To: Ramsay Jones; +Cc: git, Patrick Steinhardt
In-Reply-To: <xmqq1qbnktnl.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
>
>>> -may contain the SHA-1 name of an object or the name of another ref. Refs
>>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>>> +may contain the SHA-1 name of an object or the name of another ref (the
>>> +latter is called a "symbolic ref").
>>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>>
>> Hmm, s:ref/head:refs/heads: right?
>
> Yeah, right, not a new problem with this change, but is indeed a
> good thing to catch and correct. Thanks for a careful review.
And we have ref/tags/ just below, which I also have fixed locally.
^ permalink raw reply
* [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy
From: Junio C Hamano @ 2023-12-15 22:28 UTC (permalink / raw)
To: git; +Cc: Ramsay Jones
In-Reply-To: <xmqqttojjegr.fsf@gitster.g>
There is no 'ref/notes/' hierarchy. '[format] notes = foo' uses notes
that are found in 'refs/notes/foo'.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
* According to my eyeballing "git grep refs/ Documentation" result,
this was the only remaining mention of "ref/" in Documentation/
hierarchy that misspells "refs/".
Documentation/config/format.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git c/Documentation/config/format.txt w/Documentation/config/format.txt
index c98412b697..7410e930e5 100644
--- c/Documentation/config/format.txt
+++ w/Documentation/config/format.txt
@@ -119,7 +119,7 @@ format.notes::
`--notes=<ref>`, where `ref` is the non-boolean value. Defaults
to false.
+
-If one wishes to use the ref `ref/notes/true`, please use that literal
+If one wishes to use the ref `refs/notes/true`, please use that literal
instead.
+
This configuration can be specified multiple times in order to allow
^ permalink raw reply related
* Re: [PATCH 1/5] git.txt: HEAD is not that special
From: Ramsay Jones @ 2023-12-15 22:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Patrick Steinhardt
In-Reply-To: <xmqqttojjegr.fsf@gitster.g>
On 15/12/2023 22:19, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
>>
>>>> -may contain the SHA-1 name of an object or the name of another ref. Refs
>>>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>>>> +may contain the SHA-1 name of an object or the name of another ref (the
>>>> +latter is called a "symbolic ref").
>>>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>>>
>>> Hmm, s:ref/head:refs/heads: right?
>>
>> Yeah, right, not a new problem with this change, but is indeed a
>> good thing to catch and correct. Thanks for a careful review.
>
> And we have ref/tags/ just below, which I also have fixed locally.
Heh, yeah I missed that, along with 'ref/notes'. ;)
ATB,
Ramsay Jones
^ permalink raw reply
* Re: [PATCH 0/5] make room for "special ref"
From: Ramsay Jones @ 2023-12-15 22:44 UTC (permalink / raw)
To: Junio C Hamano, git; +Cc: Patrick Steinhardt
In-Reply-To: <xmqq5y0zkvqx.fsf@gitster.g>
On 15/12/2023 21:21, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> ... For example, FETCH_HEAD currently stores not
>> just a single object name, but can and is used to store multiple
>> object names, each with annotations to record where they came from.
>> There indeed may be a need to introduce a new term to refer to such
>> "special refs".
>
> The "may be" here vaguely hints another possibility. If we manage
> to get rid of the "special refs", we do not even have to mention
> "special refs", and more importantly, we do not need extra code to
> deal with them.
>
> For FETCH_HEAD, for example, I wonder if an update along this line
> is possible:
>
> * Teach "git fetch" to store what it writes to FETCH_HEAD to a
> different file, under a distinctly different filename (e.g.,
> $GIT_DIR/fetched-tips). Demote FETCH_HEAD to a pseudoref, and
> store the first object name in that "fetched-tips" file to it.
>
> * Teach "git pull" to learn what it used to learn from FETCH_HEAD
> (i.e., list of fetched tips, each annotated with what ref at what
> repository it came from and if it is to be merged) from the new
> "fetched-tips" file.
>
> The "special" ness of FETCH_HEAD is really an implementation detail
> of how "git pull" works and how the findings of "git fetch" are
> communicated to "git pull". The general refs API should not have to
> worry about it, and the refs backends should not have to worry about
> storing more than just an object name (or if it is a symbolic ref,
> the target refname).
>
> An end-user command like "git log ORIG_HEAD..FETCH_HEAD" would not
> be affected by changes along the above line, because the current
> FETCH_HEAD, when used as a revision, will work as if it stores the
> single object name that is listed first in the file.
>
> If somebody is reading FETCH_HEAD and acting on its contents (rather
> than merely consuming it as a ref of the first object), perhaps
> feeding it to "git fmt-merge-msg", they will be broken by such a
> change (indeed, our own "git pull" will be broken by the change to
> "git fetch", and the second bullet point above is about fixing the
> exact fallout from it), but I am not sure if that is a use case worth
> worrying about.
>
> Hmm?
>
Yes, I was going to suggest exactly this, after Patrick pointed out
that there were only two 'special psuedo-refs' (I had a vague feeling
there were some more than that) FETCH_HEAD and MERGE_HEAD.
ATB,
Ramsay Jones
^ permalink raw reply
* Re: [PATCH 0/5] make room for "special ref"
From: Junio C Hamano @ 2023-12-16 0:44 UTC (permalink / raw)
To: Ramsay Jones; +Cc: git, Patrick Steinhardt
In-Reply-To: <321b8084-fddb-4b5d-86af-7f88cb3edf7b@ramsayjones.plus.com>
Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
> Yes, I was going to suggest exactly this, after Patrick pointed out
> that there were only two 'special psuedo-refs' (I had a vague feeling
> there were some more than that) FETCH_HEAD and MERGE_HEAD.
Glad to see that I am not alone. We should be able to treat
MERGE_HEAD similarly. It is used to communicate the list of "other
parents" from "git merge" that stops in the middle (either for merge
conflict, or in response to the "--no-commit" command line option)
to "git commit" that concludes such an unfinished merge. Many
commands merely use the presence of MERGE_HEAD as a sign that a
merge is in progress (e.g. "git status"), which would not break if
we just started to record the first parent in a pseudoref MERGE_HEAD
and wrote the other octopus parents elsewhere, but some commands do
need all these parents from MERGE_HEAD (e.g. "git blame" that
synthesizes a fake starting commit out of the working tree state).
If we cannot get rid of all "special refs" anyway, however, I think
there is little that we can gain from doing such "make FETCH_HEAD
and MERGE_HEAD into a single-object pseudoref, and write other info
in separate files" exercise. We can treat the current FETCH_HEAD
and MERGE_HEAD as "file that is not and is more than a ref", which
is what the current code is doing anyway, which means we would
declare that they have to stay to be files under $GIT_DIR/ and will
be accessed via the filesystem access. At that point, calling them
"special ref" might even be more misleading than its worth and we
may be better off to admit that they are not even refs but a
datafile some commands can use to obtain input from, but the phrase
we use to refer to them, be it "special ref" or some random
datafile, does not make a fundamental change on anything.
^ permalink raw reply
* Re: [PATCH 3/5] refs.h: HEAD is not that special
From: Andy Koppe @ 2023-12-16 10:03 UTC (permalink / raw)
To: Junio C Hamano, git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-4-gitster@pobox.com>
On 15/12/2023 20:32, Junio C Hamano wrote:
> In-code comment explains pseudorefs but used a wrong nomenclature
> "special ref".
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> refs.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/refs.h b/refs.h
> index 23211a5ea1..ff113bb12a 100644
> --- a/refs.h
> +++ b/refs.h
> @@ -56,7 +56,7 @@ struct worktree;
> * Even with RESOLVE_REF_ALLOW_BAD_NAME, names that escape the refs/
> * directory and do not consist of all caps and underscores cannot be
> * resolved. The function returns NULL for such ref names.
> - * Caps and underscores refers to the special refs, such as HEAD,
> + * Caps and underscores refers to the pseudorefs, such as HEAD,
> * FETCH_HEAD and friends, that all live outside of the refs/ directory.
> */
> #define RESOLVE_REF_READING 0x01
gitglossary thinks that HEAD is not a pseudoref:
"Pseudorefs are a class of files under $GIT_DIR which behave like refs
for the purposes of rev-parse, but which are treated specially by git.
Pseudorefs both have names that are all-caps, and always start with a
line consisting of a SHA‐1 followed by whitespace. So, HEAD is not a
pseudoref, because it is sometimes a symbolic ref."
(Also, the "sometimes" there actually is "whenever you're on a branch",
which is most of the time for most people.)
Regards,
Andy
^ permalink raw reply
* Re: [PATCH 0/5] make room for "special ref"
From: Andy Koppe @ 2023-12-16 10:20 UTC (permalink / raw)
To: Ramsay Jones, Junio C Hamano, git; +Cc: Patrick Steinhardt
In-Reply-To: <321b8084-fddb-4b5d-86af-7f88cb3edf7b@ramsayjones.plus.com>
On 15/12/2023 22:44, Ramsay Jones wrote:
> On 15/12/2023 21:21, Junio C Hamano wrote:
>> If somebody is reading FETCH_HEAD and acting on its contents (rather
>> than merely consuming it as a ref of the first object), perhaps
>> feeding it to "git fmt-merge-msg", they will be broken by such a
>> change (indeed, our own "git pull" will be broken by the change to
>> "git fetch", and the second bullet point above is about fixing the
>> exact fallout from it), but I am not sure if that is a use case worth
>> worrying about.
>
> Yes, I was going to suggest exactly this, after Patrick pointed out
> that there were only two 'special psuedo-refs' (I had a vague feeling
> there were some more than that) FETCH_HEAD and MERGE_HEAD.
According to the pseudoref entry of gitglossary, CHERRY_PICK_HEAD also
stores additional data (which would imply that REVERT_HEAD does too).
Looking at CHERRY_PICK_HEAD during a pick though, I only see a single
hash, even when picking multiple commits.
Regards,
Andy
^ permalink raw reply
* Re: [PATCH] Use ^=1 to toggle between 0 and 1
From: René Scharfe @ 2023-12-16 10:46 UTC (permalink / raw)
To: Junio C Hamano, Phillip Wood
Cc: Jeff King, AtariDreams via GitGitGadget, git, Seija Kijin
In-Reply-To: <xmqqo7erl7er.fsf@gitster.g>
Am 15.12.23 um 18:09 schrieb Junio C Hamano:
> Phillip Wood <phillip.wood123@gmail.com> writes:
>
>> Even if it unlikely that we would directly compare a boolean variable
>> to "true" or "false" it is certainly conceivable that we'd compare two
>> boolean variables directly. For the integer fallback to be safe we'd
>> need to write
>>
>> if (!cond_a == !cond_b)
>>
>> rather than
>>
>> if (cond_a == cond_b)
>
> Eek, it defeats the benefit of using true Boolean type if we had to
> train ourselves to write the former, doesn't it?
Indeed.
>> [1] 7bc341e21b (git-compat-util: add a test balloon for C99 support,
>> 2021-12-01)
>
> Nice to be reminded of this one.
>
> The cited commit does not start to use any specific feature from
> C99, other than that we now require that the compiler claims C99
> conformance by __STDC_VERSION__ set appropriately. The commit log
> message says C99 "provides a variety of useful features, including
> ..., many of which we already use.", which implies that our wish was
> to officially allow any and all features in C99 to be used in our
> codebase after a successful flight of this test balloon.
>
> Now, I think we saw a successful flight of this test balloon by now.
> Is allowing all the C99 the next step we really want to take?
>
> I still personally have an aversion against decl-after-statement and
> //-comments, not due to portability reasons at all, but because I
> find that the code is easier to read without it. But in principle,
> it is powerful to be able to say "OK, as long as the feature is in
> C99 you can use it", instead of having to decide on individual
> features, and I am not fundamentally against going that route if it
> is where people want to go.
C99 added a lot of features, but we already use several of them.
Support for individual features may vary, though -- who knows?
E.g. http://www.compilers.de/vbcc.html claims to support "most of
ISO/IEC 9899:1999 (C99)", yet _Bool is not mentioned in its docs (but
__STDC_VERSION__ 199901L is). It's not a particularly interesting
compiler for us, but still a real-world example of selective C99
support.
The table at the bottom of https://en.cppreference.com/w/c/99 would be
useful if it was filled out for more compilers. And it also doesn't
mention _Bool and stdbool.h.
TenDRA and the M/o/Vfuscator are the only compilers without stdbool.h
support on https://godbolt.org/ as far as I can see, but that website
doesn't have a lot of commercial compilers (understandably).
So I guess in practice we still need to check each new feature, even
though in theory we should be fine after the two-year test.
René
^ permalink raw reply
* [PATCH] git-compat-util: convert skip_{prefix,suffix}{,_mem} to bool
From: René Scharfe @ 2023-12-16 10:47 UTC (permalink / raw)
To: git
Cc: AtariDreams via GitGitGadget, Seija Kijin, Junio C Hamano,
Jeff King, Phillip Wood
In-Reply-To: <99b3a727-36fd-4fa5-a6be-60ae6fc5911e@gmail.com>
Use the data type bool and its values true and false to document the
binary return value of skip_prefix() and friends more explicitly.
This first use of stdbool.h, introduced with C99, is meant to check
whether there are platforms that claim support for C99, as tested by
7bc341e21b (git-compat-util: add a test balloon for C99 support,
2021-12-01), but still lack that header for some reason.
A fallback based on a wider type, e.g. int, would have to deal with
comparisons somehow to emulate that any non-zero value is true:
bool b1 = 1;
bool b2 = 2;
if (b1 == b2) puts("This is true.");
int i1 = 1;
int i2 = 2;
if (i1 == i2) puts("Not printed.");
#define BOOLEQ(a, b) (!(a) == !(b))
if (BOOLEQ(i1, i2)) puts("This is true.");
So we'd be better off using bool everywhere without a fallback, if
possible. That's why this patch doesn't include any.
Signed-off-by: René Scharfe <l.s.r@web.de>
---
git-compat-util.h | 42 ++++++++++++++++++++++--------------------
1 file changed, 22 insertions(+), 20 deletions(-)
diff --git a/git-compat-util.h b/git-compat-util.h
index 3e7a59b5ff..603c97e3b3 100644
--- a/git-compat-util.h
+++ b/git-compat-util.h
@@ -225,6 +225,7 @@ struct strbuf;
#include <stddef.h>
#include <stdlib.h>
#include <stdarg.h>
+#include <stdbool.h>
#include <string.h>
#ifdef HAVE_STRINGS_H
#include <strings.h> /* for strcasecmp() */
@@ -684,11 +685,11 @@ report_fn get_warn_routine(void);
void set_die_is_recursing_routine(int (*routine)(void));
/*
- * If the string "str" begins with the string found in "prefix", return 1.
+ * If the string "str" begins with the string found in "prefix", return true.
* The "out" parameter is set to "str + strlen(prefix)" (i.e., to the point in
* the string right after the prefix).
*
- * Otherwise, return 0 and leave "out" untouched.
+ * Otherwise, return false and leave "out" untouched.
*
* Examples:
*
@@ -699,57 +700,58 @@ void set_die_is_recursing_routine(int (*routine)(void));
* [skip prefix if present, otherwise use whole string]
* skip_prefix(name, "refs/heads/", &name);
*/
-static inline int skip_prefix(const char *str, const char *prefix,
- const char **out)
+static inline bool skip_prefix(const char *str, const char *prefix,
+ const char **out)
{
do {
if (!*prefix) {
*out = str;
- return 1;
+ return true;
}
} while (*str++ == *prefix++);
- return 0;
+ return false;
}
/*
* Like skip_prefix, but promises never to read past "len" bytes of the input
* buffer, and returns the remaining number of bytes in "out" via "outlen".
*/
-static inline int skip_prefix_mem(const char *buf, size_t len,
- const char *prefix,
- const char **out, size_t *outlen)
+static inline bool skip_prefix_mem(const char *buf, size_t len,
+ const char *prefix,
+ const char **out, size_t *outlen)
{
size_t prefix_len = strlen(prefix);
if (prefix_len <= len && !memcmp(buf, prefix, prefix_len)) {
*out = buf + prefix_len;
*outlen = len - prefix_len;
- return 1;
+ return true;
}
- return 0;
+ return false;
}
/*
- * If buf ends with suffix, return 1 and subtract the length of the suffix
- * from *len. Otherwise, return 0 and leave *len untouched.
+ * If buf ends with suffix, return true and subtract the length of the suffix
+ * from *len. Otherwise, return false and leave *len untouched.
*/
-static inline int strip_suffix_mem(const char *buf, size_t *len,
- const char *suffix)
+static inline bool strip_suffix_mem(const char *buf, size_t *len,
+ const char *suffix)
{
size_t suflen = strlen(suffix);
if (*len < suflen || memcmp(buf + (*len - suflen), suffix, suflen))
- return 0;
+ return false;
*len -= suflen;
- return 1;
+ return true;
}
/*
- * If str ends with suffix, return 1 and set *len to the size of the string
- * without the suffix. Otherwise, return 0 and set *len to the size of the
+ * If str ends with suffix, return true and set *len to the size of the string
+ * without the suffix. Otherwise, return false and set *len to the size of the
* string.
*
* Note that we do _not_ NUL-terminate str to the new length.
*/
-static inline int strip_suffix(const char *str, const char *suffix, size_t *len)
+static inline bool strip_suffix(const char *str, const char *suffix,
+ size_t *len)
{
*len = strlen(str);
return strip_suffix_mem(str, len, suffix);
--
2.43.0
^ permalink raw reply related
* Re: [PATCH 0/5] make room for "special ref"
From: Andy Koppe @ 2023-12-16 10:56 UTC (permalink / raw)
To: Junio C Hamano, git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-1-gitster@pobox.com>
On 15/12/2023 20:32, Junio C Hamano wrote:
> A pseudo ref is merely a normal ref with a funny naming convention,
> i.e., being outside the refs/ hierarchy and has names with all
> uppercase letters (or an underscore).
I know what you mean, but gitglossary defines pseudorefs as separate
from refs, albeit behaving like refs. Their name itself implies the same.
Although the 'ref' entry then goes on to say that "there are a few
special-purpose refs that do not begin with 'refs/', the most notable
example being HEAD."
That implies that at least some of the pseudorefs are refs after all,
while keeping in mind that "HEAD is not a pseudoref, because it is
sometimes a symbolic ref" according to the 'pseudoref' entry.
I think a clearer answer on whether pseudorefs are refs is needed, or at
least a better-defined fudge, such as "pseudorefs are refs except when ...".
Defining everything under "refs/" as refs, and the stuff outside it
including HEAD itself as pseudorefs, would draw clearer lines. The fact
HEAD is usually symbolic doesn't seem all that relevant from the
perspective of a user trying to get a grasp of refs and pseudorefs.
Regards,
Andy
^ permalink raw reply
* Re: [PATCH 5/5] docs: MERGE_AUTOSTASH is not that special
From: Andy Koppe @ 2023-12-16 11:04 UTC (permalink / raw)
To: Junio C Hamano, git; +Cc: Patrick Steinhardt
In-Reply-To: <20231215203245.3622299-6-gitster@pobox.com>
On 15/12/2023 20:32, Junio C Hamano wrote:
> A handful of manual pages called MERGE_AUTOSTASH a "special ref",
> but there is nothing special about it. It merely is yet another
> pseudoref.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/merge-options.txt | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index d8f7cd7ca0..3eaefc4e94 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -191,7 +191,7 @@ endif::git-pull[]
> --autostash::
> --no-autostash::
> Automatically create a temporary stash entry before the operation
> - begins, record it in the special ref `MERGE_AUTOSTASH`
> + begins, record it in the ref `MERGE_AUTOSTASH`
> and apply it after the operation ends. This means
> that you can run the operation on a dirty worktree. However, use
> with care: the final stash application after a successful
Should that say 'pseudoref' instead of 'ref'?
And since MERGE_AUTOSTASH is documented here, it probably should be in
gitrevisions as well.
Regards,
Andy
^ permalink raw reply
* Re: Propose a change in open for passing in the file type.
From: Torsten Bögershausen @ 2023-12-16 13:28 UTC (permalink / raw)
To: Đoàn Trần Công Danh; +Cc: Haritha D, git@vger.kernel.org
In-Reply-To: <ZXkwTYD9nmPYn9UW@danh.dev>
On Wed, Dec 13, 2023 at 11:17:17AM +0700, Đoàn Trần Công Danh wrote:
[]
> Would it work if you always open the file as BINARY?
Yes, I think so.
> And let's all the
> conversion done by git via some configs (core.encoding?)?
We already have an attribute, "working-tree-encoding", that
can tell Git to do the encoding/reencoding.
The advantage of the .gitattributes file is, that it is
typically commit into the repo, and travels with `git push`
and `git fetch` or `git pull` to the different work stations,
so that everybody has the same settings.
In opposite, config files are always local.
So that everybody should do the same (local) git config.
If that is forgotten for some reason, then different
configurations leads often to some kind of chaos.
But I don't have a z/os sytem to test on.
^ permalink raw reply
* MyFirstContribution.txt leaks memory
From: Vinayak Dev @ 2023-12-16 13:45 UTC (permalink / raw)
To: git
Hello everyone!
I was going through the MyFirstContribution tutorial and implemented
its code as an exercise to warm up my git skills.
However, when I pushed the code to my fork on GitHub, I noticed that
it fails the linux-leaks test.
So I fired up the leaks checker that MacOS provides and got a number
of leaks in the tutorial code.
One was that the strbuf commitline was not released, so I was able to
fix that trivially.
However, the stack trace for the second leak shows that the memory
leaks when git_config() is called on the wt_status struct, which in turn
calls the git_default_config() function. As it must go through my
.gitconfig, I noticed that when it checks for "core.editor", it calls
git_config_string(), where the string is duplicated into the
editor_program variable.
This is precisely where the leak seems to be, as pointed out by the
stack of function calls. I thought that maybe freeing dest as in
free((void *)*dest) in git_config_string() before calling xstrdup()
might free up the leakage (this has been done in a number of places in
the code-base).
While this does free up the leakage, I am getting a number of failures in
the test suite(some of which are occurring even without the changes),
particularly related to setting up bare repositories.
Also, as only the tutorial code's binary(./bin-wrappers/git psuh) that I
implemented leaks memory, I suspect that it is my fault somewhere.
Could anyone point out what is the correct way to free up memory in this case?
Or would the situation warrant adding the call to free() in git_config_string()?
Thanks a lot!
Vinayak
^ permalink raw reply
* Question: rerere preimage format
From: Mohamed Mohey @ 2023-12-16 15:46 UTC (permalink / raw)
To: git
Hi,
I was reading the Rerere section of the Pro Git book when I came
across the following snippet:
$ git rerere diff
--- a/hello.rb
+++ b/hello.rb
@@ -1,11 +1,11 @@
#! /usr/bin/env ruby
def hello
-<<<<<<<
- puts 'hello mundo'
-=======
+<<<<<<< HEAD
puts 'hola world'
->>>>>>>
+=======
+ puts 'hello mundo'
+>>>>>>> i18n-world
end
If I understand correctly, this is the diff between rerere's preimage
and the version in the current working directory, as explained in this
StackOverflow answer:
https://stackoverflow.com/a/27364585
What I don't understand, however, is why rerere records its initial
preimage without labels. This seems to have been rerere's behavior
ever since it was introduced as a perl script back in 2006:
https://lore.kernel.org/git/7v4q3no0v7.fsf@assigned-by-dhcp.cox.net/
+ $one = join('', @{$side[0]});
+ $two = join('', @{$side[1]});
+ if ($two le $one) {
+ ($one, $two) = ($two, $one);
+ }
+ print $out "<<<<<<<\n";
+ print $out $one;
+ print $out "=======\n";
+ print $out $two;
+ print $out ">>>>>>>\n";
+ @side = ();
So the preimage format doesn't contain any labels, and outputs the
lexicographically smaller hunk first,
while the default merge conflict output has labels and outputs the
current branch first followed by the other branch.
If rerere recorded its preimage in the same format as the default
merge conflict format,
the above rerere diff output would be empty as there would be no
difference between what we started with and what we resolved into.
The same behaviour would still occur with the diff3 style format, for
example, but at least it wouldn't occur with the default merge style
format.
My question is:
Is there a reason rerere's output is like this that I'm missing? Or is
it just there for convenience since it doesn't affect rerere's
intended functionality?
Thanks,
Mohamed Mohey
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox