From: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> This series removes or moves some old material in the update-ref doc and improves the discussion of symrefs, opting for a high-level description with some redundancy (see patch 5/6) in order to avoid a reported mistake/confusion. The end goal (after all patches are applied): • First paragraph (in Description) describes the first form • Second paragraph the second form • Third paragraph mentions symrefs and explains why `--stdin` supports them • A new section whither the symlink (FS) vs. symrefs discussion is moved • Link update-ref to symbolic-ref and vice versa § Changes in v2 See notes on the patches for all changes. Some of the minor ones are omitted here. • Diff changes (see interdiff): • Fix “the the” • All: Taylor suggested changing the “area” prefix • (but I kept it on the series for consistency) • Link: https://lore.kernel.org/git/ZxAoFUDmdfZ8rlLs@nand.local/ • Patch “drop “flag” ”: • Not done: Wrap paragraph • Patch “remove confusing paragraph” • (Commit) Message tweak • Mention that what a symref is (concretely) is documented elsewhere • Patch “discuss symbolic refs”: • change subject from “symbolic links” • Credit Bence Kristoffer Haugsbakk (6): Documentation/git-update-ref.txt: drop “flag” Documentation/git-update-ref.txt: remove safety paragraphs Documentation/git-update-ref.txt: demote symlink to last section Documentation/git-update-ref.txt: remove confusing paragraph Documentation/git-update-ref.txt: discuss symbolic refs Documentation: mutually link update-ref and symbolic-ref Documentation/git-symbolic-ref.txt | 4 +++ Documentation/git-update-ref.txt | 48 +++++++++++++----------------- 2 files changed, 25 insertions(+), 27 deletions(-) Interdiff against v1: diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index fada3f670eb..c64d80f5a2d 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -28,8 +28,8 @@ not exist. The final arguments are object names; this command without any options does not support updating a symbolic ref to point to another ref (see linkgit:git-symbolic-ref[1]). But `git update-ref --stdin` does have -the the `symref-*` commands so that regular refs and symbolic refs can -be committed in the same transaction. +the `symref-*` commands so that regular refs and symbolic refs can be +committed in the same transaction. If --no-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers. Range-diff against v1: 1: ad9ee00a2a9 ! 1: 91c1cae3209 doc: update-ref: drop “flag” @@ Metadata Author: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Commit message ## - doc: update-ref: drop “flag” + Documentation/git-update-ref.txt: drop “flag” - The other paragraphs on options say `With <option>,`. Let’s be uniform. + The other paragraphs on options say “With <option>,”. Let’s be uniform. Signed-off-by: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> + + ## Notes (series) ## + v2: + • Message: tweak + • Not done: paragraph wrapping. I found something else in this + paragraph: missing “that”: “after verifying *that*”. I will fix that + in an upcoming series since there were four other missing instances of + this word and I did not want to add another patch to this series. + ## Documentation/git-update-ref.txt ## @@ Documentation/git-update-ref.txt: for reading but not for writing (so we'll never write through a ref symlink to some other tree, if you have copied a whole 2: c4bc0553a30 ! 2: 71d1e6364a2 doc: update-ref: remove safety paragraphs @@ Metadata Author: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Commit message ## - doc: update-ref: remove safety paragraphs + Documentation/git-update-ref.txt: remove safety paragraphs Remove paragraphs which explain that using this command is safer than echoing the branch name into `HEAD`. 3: 3f43ddfed24 ! 3: ca786bff978 doc: update-ref: demote symlink to last section @@ Metadata Author: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Commit message ## - doc: update-ref: demote symlink to last section + Documentation/git-update-ref.txt: demote symlink to last section Move the discussion of file system symbolic links to a new “Notes” section (inspired by the one in git-symbolic-ref(1)) since this is 4: dec48e2d37c ! 4: 769fd20945d doc: update-ref: remove confusing paragraph @@ Metadata Author: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Commit message ## - doc: update-ref: remove confusing paragraph + Documentation/git-update-ref.txt: remove confusing paragraph - This paragraph interrupts the flow of this section by going into detail + This paragraph interrupts the flow of the 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 @@ Commit message 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. + gitglossary(7) already documents what a symref is, concretely, and quite + well at that. + Reported-by: Bence Ferdinandy <bence@xxxxxxxxxxxxxx> Signed-off-by: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Notes (series) ## - This paragraph is also from the initial documentation: 129056370ab (Add - missing documentation., 2005-10-04). + v2: + • Message: replace “this” with “the”, which avoids two “this” close to + each other + • Message: Mention that what a symref is (concretely) is covered + by gitglossary(7) ## Documentation/git-update-ref.txt ## @@ Documentation/git-update-ref.txt: value is <old-oid>. You can specify 40 "0" or an empty string 5: 3575fb48c93 ! 5: ca5ece5336c doc: update-ref: discuss symbolic links @@ Metadata Author: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Commit message ## - doc: update-ref: discuss symbolic links + Documentation/git-update-ref.txt: discuss symbolic refs Add a paragraph which just emphasizes that the command without any - options does not support refs in the final arguments. This is - clear already from the names `<new-oid>` and `<old-oid>` but the right - balance of redundancy makes documentation robust to stray - interpretation. + options does not support refs in the final arguments. This is clear + already from the names `<new-oid>` and `<old-oid>` but the right balance + of redundancy makes documentation robust against stray interpretation. This is also a good place to mention why `--stdin` has those `symref-*` commands. + Suggested-by: Bence Ferdinandy <bence@xxxxxxxxxxxxxx> Signed-off-by: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> + + ## Notes (series) ## + v2: + • Message: grammar: “robust against” + • Message: Apparently the first paragraph wasn’t wrapped properly + • Fix “the the” + • Credit Bence for this suggestion which I forgot to do in v1 + + Link: https://lore.kernel.org/git/D4U30MD29CJT.3US5SBR598DVY@xxxxxxxxxxxxxx/ + • Message: “symbolic refs”, not links + ## Documentation/git-update-ref.txt ## @@ Documentation/git-update-ref.txt: 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 @@ Documentation/git-update-ref.txt: value is <old-oid>. You can specify 40 "0" or +The final arguments are object names; this command without any options +does not support updating a symbolic ref to point to another ref (see +linkgit:git-symbolic-ref[1]). But `git update-ref --stdin` does have -+the the `symref-*` commands so that regular refs and symbolic refs can -+be committed in the same transaction. ++the `symref-*` commands so that regular refs and symbolic refs can be ++committed in the same transaction. + If --no-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers. 6: 9e775a65eb3 ! 6: fd3c7585a0f doc: mutually link update-ref and symbolic-ref @@ Metadata Author: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Commit message ## - doc: mutually link update-ref and symbolic-ref + Documentation: mutually link update-ref and symbolic-ref These two commands are similar enough to acknowledge each other on their documentation pages. base-commit: ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f -- 2.46.1.641.g54e7913fcb6
