{"thread":{"id":"20359","subject":"[PATCH] git-tag(1): Refer to git-check-ref-format(1) for ","startedAt":"2009-08-03T18:20:02Z","lastAt":"2009-08-25T20:37:14Z","messageCount":6,"participants":["Jari Aalto","Junio C Hamano","Nanako Shiraishi"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"119423","messageId":"87ab2gsqst.fsf@jondo.cante.net","threadId":"20359","inReplyTo":null,"subject":"[PATCH] git-tag(1): Refer to git-check-ref-format(1) for ","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-03T18:20:02Z","receivedAt":"2009-08-03T18:20:02Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Explain briefly what characters are prohibited in tag \nand point to git-check-ref-format(1) manual page for\nmore information.\n---\n Documentation/git-tag.txt | 5 ++++-\n 1 files changed, 4 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex fa73321..1118ce2 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -17,7 +17,10 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Adds a 'tag' reference in `.git/refs/tags/`\n+\n+Adds a 'tag' reference in `.git/refs/tags/`. The tag must pass\n+linkgit:git-check-ref-format[1] which basicly means that control characters,\n+space, ~, ^, :, ?, *, [ and \\ are prohibited.\n \n Unless `-f` is given, the tag must not yet exist in\n `.git/refs/tags/` directory.\n-- \n1.6.3.3\n"},{"id":"119462","messageId":"7veirs6qxn.fsf@alter.siamese.dyndns.org","threadId":"20359","inReplyTo":"87ab2gsqst.fsf@jondo.cante.net","subject":"Re: [PATCH] git-tag(1): Refer to git-check-ref-format(1) for ","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-04T06:20:20Z","receivedAt":"2009-08-04T06:20:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> Explain briefly what characters are prohibited in tag \n> and point to git-check-ref-format(1) manual page for\n> more information.\n> ---\n\nThanks.\n\nI do not see a reason to reject this patch (other than lack of sign-off),\nbut at the same time, I wish if we can somehow teach people that the\nbranches and the tags are just two special cases of refs that follow\nexactly the same set of rules, we would not have to apply another similar\npatch to git-branch documentation and instead we can teach what the naming\nrules are for refs in general. Then the readers can learn the rule once,\nand extend the knowledge to other types of refs (e.g. notes) in the\nfuture.\n\nI however do not think of a way to organize our documentations without too\nmany levels of indirections (e.g. repeating \"X is just a ref and for\nnaming rules, see check-ref-format(1)\" for all types X of refs). Not\nrepeating the rules for documentation of each kind of ref will make the\nmaintenance a lot easier but hurts readability, but the set of rules is\nnot a large enough to justify the complexity to use a separate include\nfile at the source level.\n"},{"id":"119701","messageId":"8763d2klen.fsf@jondo.cante.net","threadId":"20359","inReplyTo":"7veirs6qxn.fsf@alter.siamese.dyndns.org","subject":"[PATCH] git-tag(1): Refer to git-check-ref-format(1) for ","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-05T21:20:32Z","receivedAt":"2009-08-05T21:20:32Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Explain briefly what characters are prohibited in tag \nand point to git-check-ref-format(1) manual page for\nfurther information.\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-tag.txt | 5 ++++-\n 1 files changed, 4 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex fa73321..1118ce2 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -17,7 +17,10 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Adds a 'tag' reference in `.git/refs/tags/`\n+\n+Adds a 'tag' reference in `.git/refs/tags/`. The tag must pass\n+linkgit:git-check-ref-format[1] which basicly means that control characters,\n+space, ~, ^, :, ?, *, [ and \\ are prohibited.\n \n Unless `-f` is given, the tag must not yet exist in\n `.git/refs/tags/` directory.\n-- \n1.6.3.3\n"},{"id":"121481","messageId":"20090822094518.6117@nanako3.lavabit.com","threadId":"20359","inReplyTo":"7veirs6qxn.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-tag(1): Refer to git-check-ref-format(1) for ","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-08-22T00:45:18Z","receivedAt":"2009-08-22T00:45:18Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Junio C Hamano \n\n but at the same time, I wish if we can somehow teach people that the\n branches and the tags are just two special cases of refs that follow\n exactly the same set of rules, we would not have to apply another\n similar patch to git-branch documentation and instead we can teach what\n the naming rules are for refs in general. Then the readers can learn\n the rule once, and extend the knowledge to other types of refs\n (e.g. notes) in the future.\n\nI read the help page for the git-branch command and noticed that we don't\nneed a similar patch. I think the git-branch help is nicer than git-tag\nhelp because it doesn't reproduce the rule in an incomplete way that can\nlead to confusion, divergence, and additional maintenance hassle.\n\n-- 8< -- 8< -- 8< -- cut here >8 -- >8 -- >8 --\n\nSubject: Documentation: consistently refer to check-ref-format\n\nChange the placeholder to in the SYNOPSIS section of\ngit-tag documentation, and describe it in the OPTIONS section in a way\nsimilar to how documentation for git-branch does.\n\nAdd SEE ALSO section to list the other documentation pages these two pages\nrefer to.\n\nSigned-off-by: Nanako Shiraishi \n---\n\n Documentation/git-branch.txt | 6 ++++++\n Documentation/git-tag.txt | 20 ++++++++++++++------\n 2 files changed, 20 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ae201de..9998887 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -209,6 +209,12 @@ but different purposes:\n - `--no-merged` is used to find branches which are candidates for merging\n into HEAD, since those branches are not fully contained by HEAD.\n \n+SEE ALSO\n+--------\n+linkgit:git-check-ref-format[1],\n+linkgit:git-fetch[1],\n+linkgit:git-remote[1].\n+\n Author\n ------\n Written by Linus Torvalds and Junio C Hamano \ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 1118ce2..5113eae 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -10,17 +10,15 @@ SYNOPSIS\n --------\n [verse]\n 'git tag' [-a | -s | -u ] [-f] [-m | -F ]\n-\t [ | ]\n-'git tag' -d ...\n+\t [ | ]\n+'git tag' -d ...\n 'git tag' [-n[]] -l [--contains ] []\n-'git tag' -v ...\n+'git tag' -v ...\n \n DESCRIPTION\n -----------\n \n-Adds a 'tag' reference in `.git/refs/tags/`. The tag must pass\n-linkgit:git-check-ref-format[1] which basicly means that control characters,\n-space, ~, ^, :, ?, *, [ and \\ are prohibited.\n+Adds a tag reference in `.git/refs/tags/`.\n \n Unless `-f` is given, the tag must not yet exist in\n `.git/refs/tags/` directory.\n@@ -88,6 +86,12 @@ OPTIONS\n \tImplies `-a` if none of `-a`, `-s`, or `-u `\n \tis given.\n \n+::\n+\tThe name of the tag to create, delete, or describe.\n+\tThe new tag name must pass all checks defined by\n+\tlinkgit:git-check-ref-format[1]. Some of these checks\n+\tmay restrict the characters allowed in a tag name.\n+\n CONFIGURATION\n -------------\n By default, 'git-tag' in sign-with-default mode (-s) will use your\n@@ -252,6 +256,10 @@ $ GIT_COMMITTER_DATE=\"2006-10-02 10:31\" git tag -s v1.0.1\n ------------\n \n \n+SEE ALSO\n+--------\n+linkgit:git-check-ref-format[1].\n+\n Author\n ------\n Written by Linus Torvalds ,\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"121720","messageId":"20090825172100.6117@nanako3.lavabit.com","threadId":"20359","inReplyTo":"20090822094518.6117@nanako3.lavabit.com","subject":"Re: [PATCH] git-tag(1): Refer to git-check-ref-format(1) for ","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-08-25T08:21:00Z","receivedAt":"2009-08-25T08:21:00Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting myself...\n\n> Subject: Documentation: consistently refer to check-ref-format\n>\n> Change the placeholder to in the SYNOPSIS section of\n> git-tag documentation, and describe it in the OPTIONS section in a way\n> similar to how documentation for git-branch does.\n>\n> Add SEE ALSO section to list the other documentation pages these two pages\n> refer to.\n>\n> Signed-off-by: Nanako Shiraishi \n\nShould I further polish this patch?\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"121753","messageId":"7vd46jocjp.fsf@alter.siamese.dyndns.org","threadId":"20359","inReplyTo":"20090825172100.6117@nanako3.lavabit.com","subject":"Re: [PATCH] git-tag(1): Refer to git-check-ref-format(1) for ","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-25T20:37:14Z","receivedAt":"2009-08-25T20:37:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nanako Shiraishi writes:\n\n> Quoting myself...\n>\n>> Subject: Documentation: consistently refer to check-ref-format\n>>\n>> Change the placeholder to in the SYNOPSIS section of\n>> git-tag documentation, and describe it in the OPTIONS section in a way\n>> similar to how documentation for git-branch does.\n>>\n>> Add SEE ALSO section to list the other documentation pages these two pages\n>> refer to.\n>>\n>> Signed-off-by: Nanako Shiraishi \n>\n> Should I further polish this patch?\n\nNo, it just fell through the cracks of my mailbox. I tend to agree that\nit is better to mention only the presense of rules, and refer to the rules\ndescribed in the definitive document.\n\nSafe names are designed to be what most sane people would naturally choose\nto use anyway and they would not need to see the clutter that describes\nonly the half of the rules there. And more importantly, the people who do\nget errors by choosing illegal names by accident would _want_ to see the\nfull set of rules before choosing another name to avoid getting the same\nerror again.\n\nSpelling only the half of the rules in the tag/branch manual page would\nnot help neither audience.\n"}]}