[PATCH v3 5/6] Documentation/git-update-ref.txt: discuss symbolic refs

From: kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date: Oct 21, 2024, 20:47 UTC
Message-ID: <5033ec82586691065504e429d0c21464abee945a.1729543007.git.code@khaugsbakk.name>
In-Reply-To: <cover.1729543007.git.code@khaugsbakk.name>

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 against stray interpretation.

This is also a good place to mention why `--stdin` has those `symref-*` commands.

Suggested-by: Bence Ferdinandy <bence@ferdinandy.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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@ferdinandy.com/
    • Message: “symbolic refs”, not links

 Documentation/git-update-ref.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index 61647ee8413..2e85f7ce3ee 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -25,6 +25,12 @@ 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.
 
+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 `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.

-- 
2.46.1.641.g54e7913fcb6