On Tue, Oct 15, 2024 at 09:03:13PM +0200, kristofferhaugsbakk@xxxxxxxxxxxx wrote: > From: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> > > 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
