| Message ID | dec48e2d37cc4edafb51476284ce3fece4718ce7.1729017728.git.code@khaugsbakk.name (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 793e308f1ed8197764cce8b88b4ee4e7471287df |
| Headers | show |
| Series | doc: update-ref: amend old material and discuss symrefs | expand |
On Tue, Oct 15, 2024 at 09:03:13PM +0200, kristofferhaugsbakk@fastmail.com wrote: > From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > This paragraph interrupts the flow of this section by going into detail > about what a symbolic ref file is and how it is implemented. It is not > clear what the purpose is since symbolic refs were already mentioned > prior (“possibly dereferencing the symbolic refs”). Worse, it can > confuse the reader about what argument can be a symbolic ref since it > just says “it” and not which of the parameters; in turn the reader can > be lead to try `<new-oid>` and then get a confusing error since > update-ref will just say that it is not a valid SHA1. I think that it is worth saying that this concept is explained well throughout other parts of the documentation, including other parts of 'git-update-ref(1)', as well as the glossary content. I don't think that you necessarily need to mention that here. But at least I was initially confused thinking that this patch proposed removing the only mention of the special "ref:" syntax for symbolic references. But it does not, so I think that this patch as you wrote it is good. Let's keep reading... Thanks, Taylor
On Wed, Oct 16, 2024, at 22:51, Taylor Blau wrote: > […] > > I think that it is worth saying that this concept is explained well > throughout other parts of the documentation, including other parts of > 'git-update-ref(1)', as well as the glossary content. > > I don't think that you necessarily need to mention that here. But at > least I was initially confused thinking that this patch proposed > removing the only mention of the special "ref:" syntax for symbolic > references. > > But it does not, so I think that this patch as you wrote it is good. > Let's keep reading... You/a reader in general being in doubt is enough reason to mention some other documentation source. I’ll fix in the next version. And thanks for reading!
On Wed, Oct 16, 2024 at 10:55:13PM +0200, Kristoffer Haugsbakk wrote: > On Wed, Oct 16, 2024, at 22:51, Taylor Blau wrote: > > […] > > > > I think that it is worth saying that this concept is explained well > > throughout other parts of the documentation, including other parts of > > 'git-update-ref(1)', as well as the glossary content. > > > > I don't think that you necessarily need to mention that here. But at > > least I was initially confused thinking that this patch proposed > > removing the only mention of the special "ref:" syntax for symbolic > > references. > > > > But it does not, so I think that this patch as you wrote it is good. > > Let's keep reading... > > You/a reader in general being in doubt is enough reason to mention some > other documentation source. I’ll fix in the next version. > > And thanks for reading! Thank you, and no problem ;-). Thanks, Taylor
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index c03e65404e8..4bb3389cc7c 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -25,10 +25,6 @@ value is <old-oid>. You can specify 40 "0" or an empty string as <old-oid> to make sure that the ref you are creating does not exist. -It also allows a "ref" file to be a symbolic pointer to another -ref file by starting with the four-byte header sequence of -"ref:". - If --no-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers.