Skip to contentSkip to conversation

git-tag(1): Refer to git-check-ref-format(1) for <name>

PATCH In review Jari Aalto 3 participants 6 messages Jun 15, 2016 Documentation

lore
Share & tools
lore

Jari Aalto

author
#0 lore raw

PATCH 1/1 git-tag(1): Refer to git-check-ref-format(1) for <name>

Explain briefly what characters are prohibited in tag <name> and point to git-check-ref-format(1) manual page for more information.

---
 Documentation/git-tag.txt |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)
Documentation/git-tag.txt +4 -1
index fa73321..1118ce2 100644
@@ -17,7 +17,10 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Adds a 'tag' reference in `.git/refs/tags/`
+
+Adds a 'tag' reference in `.git/refs/tags/`.  The tag <name> must pass
+linkgit:git-check-ref-format[1] which basicly means that control characters,
+space, ~, ^, :, ?, *, [ and \ are prohibited.
 
 Unless `-f` is given, the tag must not yet exist in
 `.git/refs/tags/` directory.
Signature · 1 line
1.6.3.3
#1 lore raw
Quoted 4 lines · Jari Aalto

Explain briefly what characters are prohibited in tag <name> and point to git-check-ref-format(1) manual page for more information.
---

Thanks.

I do not see a reason to reject this patch (other than lack of sign-off), but at the same time, I wish if we can somehow teach people that the branches and the tags are just two special cases of refs that follow exactly the same set of rules, we would not have to apply another similar patch to git-branch documentation and instead we can teach what the naming rules are for refs in general. Then the readers can learn the rule once, and extend the knowledge to other types of refs (e.g. notes) in the future.

I however do not think of a way to organize our documentations without too many levels of indirections (e.g. repeating "X is just a ref and for naming rules, see check-ref-format(1)" for all types X of refs). Not repeating the rules for documentation of each kind of ref will make the maintenance a lot easier but hurts readability, but the set of rules is not a large enough to justify the complexity to use a separate include file at the source level.

author
#2 lore raw

PATCH 1/1 git-tag(1): Refer to git-check-ref-format(1) for <name>

Explain briefly what characters are prohibited in tag <name> and point to git-check-ref-format(1) manual page for further information.

---
 Documentation/git-tag.txt |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)
Documentation/git-tag.txt +4 -1
index fa73321..1118ce2 100644
@@ -17,7 +17,10 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Adds a 'tag' reference in `.git/refs/tags/`
+
+Adds a 'tag' reference in `.git/refs/tags/`.  The tag <name> must pass
+linkgit:git-check-ref-format[1] which basicly means that control characters,
+space, ~, ^, :, ?, *, [ and \ are prohibited.
 
 Unless `-f` is given, the tag must not yet exist in
 `.git/refs/tags/` directory.
Signature · 1 line
1.6.3.3
#3 lore raw
In reply to Junio C Hamano

Quoting Junio C Hamano <[email protected]>

but at the same time, I wish if we can somehow teach people that the branches and the tags are just two special cases of refs that follow exactly the same set of rules, we would not have to apply another similar patch to git-branch documentation and instead we can teach what the naming rules are for refs in general. Then the readers can learn the rule once, and extend the knowledge to other types of refs (e.g. notes) in the future.

I read the help page for the git-branch command and noticed that we don't need a similar patch. I think the git-branch help is nicer than git-tag help because it doesn't reproduce the rule in an incomplete way that can lead to confusion, divergence, and additional maintenance hassle.

-- 8< -- 8< -- 8< -- cut here >8 -- >8 -- >8 --

Subject: Documentation: consistently refer to check-ref-format

Change the <name> placeholder to <tagname> in the SYNOPSIS section of git-tag documentation, and describe it in the OPTIONS section in a way similar to how documentation for git-branch does.

Add SEE ALSO section to list the other documentation pages these two pages refer to.

---

 Documentation/git-branch.txt |    6 ++++++
 Documentation/git-tag.txt    |   20 ++++++++++++++------
 2 files changed, 20 insertions(+), 6 deletions(-)
Documentation/git-branch.txt +6 -0
index ae201de..9998887 100644
@@ -209,6 +209,12 @@ but different purposes:
 - `--no-merged` is used to find branches which are candidates for merging
   into HEAD, since those branches are not fully contained by HEAD.
 
+SEE ALSO
+--------
+linkgit:git-check-ref-format[1],
+linkgit:git-fetch[1],
+linkgit:git-remote[1].
+
 Author
 ------
 Written by Linus Torvalds <[email protected]> and Junio C Hamano <[email protected]>
Documentation/git-tag.txt +14 -6
index 1118ce2..5113eae 100644
@@ -10,17 +10,15 @@ SYNOPSIS
 --------
 [verse]
 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
-	<name> [<commit> | <object>]
-'git tag' -d <name>...
+	<tagname> [<commit> | <object>]
+'git tag' -d <tagname>...
 'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>]
-'git tag' -v <name>...
+'git tag' -v <tagname>...
 
 DESCRIPTION
 -----------
 
-Adds a 'tag' reference in `.git/refs/tags/`.  The tag <name> must pass
-linkgit:git-check-ref-format[1] which basicly means that control characters,
-space, ~, ^, :, ?, *, [ and \ are prohibited.
+Adds a tag reference in `.git/refs/tags/`.
 
 Unless `-f` is given, the tag must not yet exist in
 `.git/refs/tags/` directory.
@@ -88,6 +86,12 @@ OPTIONS
 	Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
 	is given.
 
+<tagname>::
+	The name of the tag to create, delete, or describe.
+	The new tag name must pass all checks defined by
+	linkgit:git-check-ref-format[1].  Some of these checks
+	may restrict the characters allowed in a tag name.
+
 CONFIGURATION
 -------------
 By default, 'git-tag' in sign-with-default mode (-s) will use your
@@ -252,6 +256,10 @@ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
 ------------
 
 
+SEE ALSO
+--------
+linkgit:git-check-ref-format[1].
+
 Author
 ------
 Written by Linus Torvalds <[email protected]>,
Signature · 2 lines
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/
#4 lore raw

Quoting myself...

Quoted 10 lines

Subject: Documentation: consistently refer to check-ref-format

Change the <name> placeholder to <tagname> in the SYNOPSIS section of git-tag documentation, and describe it in the OPTIONS section in a way similar to how documentation for git-branch does.

Add SEE ALSO section to list the other documentation pages these two pages refer to.

Should I further polish this patch?

Signature · 2 lines
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/
#5 lore raw
Quoted 8 lines · Nanako Shiraishi

Quoting myself...

Quoted 6 lines

Subject: Documentation: consistently refer to check-ref-format

Change the <name> placeholder to <tagname> in the SYNOPSIS section of git-tag documentation, and describe it in the OPTIONS section in a way similar to how documentation for git-branch does.

Quoted 6 lines
Quoted 4 lines

Add SEE ALSO section to list the other documentation pages these two pages refer to.

Should I further polish this patch?

No, it just fell through the cracks of my mailbox. I tend to agree that it is better to mention only the presense of rules, and refer to the rules described in the definitive document.

Safe names are designed to be what most sane people would naturally choose to use anyway and they would not need to see the clutter that describes only the half of the rules there. And more importantly, the people who do get errors by choosing illegal names by accident would _want_ to see the full set of rules before choosing another name to avoid getting the same error again.

Spelling only the half of the rules in the tag/branch manual page would not help neither audience.