{"thread":{"id":"31130","subject":"git-tag documentation enhancement","startedAt":"2012-07-29T12:33:24Z","lastAt":"2012-08-06T21:04:06Z","messageCount":3,"participants":["乙酸鋰","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"196059","messageId":"CAHtLG6SQ3DeexriXRtV4ys7x12iKQtq7OCrZdC+A8SSH6Tokow@mail.gmail.com","threadId":"31130","inReplyTo":"CAHtLG6TDDmvtt1cc3_mGG9hZtSVp-ecNXzCQrPj6-e4DU6HMGA@mail.gmail.com","subject":"git-tag documentation enhancement","fromName":"乙酸鋰","fromEmail":"ch3cooli@gmail.com","sentAt":"2012-07-29T12:33:24Z","receivedAt":"2012-07-29T12:33:24Z","isPatch":false,"sender":{"key":"ch3cooli@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2804967?v=4"},"body":"Dear Sir,\n\nI would like to enhance git-tag documentation\n\n--Unless -f is given, the tag to be created must not yet exist in the\n.git/refs/tags/ directory.\n++Unless -f is given, the tag to be created must not yet exist in the\n.git/refs/tags/ directory or inside .git/packed-refs file.\n\nRegards,\nch3cooli\n"},{"id":"196096","messageId":"7vvch6t5in.fsf@alter.siamese.dyndns.org","threadId":"31130","inReplyTo":"CAHtLG6SQ3DeexriXRtV4ys7x12iKQtq7OCrZdC+A8SSH6Tokow@mail.gmail.com","subject":"Re: git-tag documentation enhancement","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-07-30T01:13:52Z","receivedAt":"2012-07-30T01:13:52Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"乙酸鋰 <ch3cooli@gmail.com> writes:\n\n> I would like to enhance git-tag documentation\n>\n> --Unless -f is given, the tag to be created must not yet exist in the\n> .git/refs/tags/ directory.\n> ++Unless -f is given, the tag to be created must not yet exist in the\n> .git/refs/tags/ directory or inside .git/packed-refs file.\n\nI think the updated text is technically correct, but I do not think\nit is a good direction to go.  The root cause of the problem was\nthat the original text assumed \".git/refs/tags/ directory\" will\nforever be the only way to have a local tag, and the description was\nleft behind when packed refs mechanism was introduced to improve the\nfile system usage.  It shouldn't have relied its description on such\nan implementation detail in the first place.\n\nThe updated text still shares the same problem.  I think the right\nfix is to say something like this:\n\n        Unless -f is given, the tag to be created must not yet exist\n        as a local tag.\n"},{"id":"196565","messageId":"7vk3xbybp5.fsf_-_@alter.siamese.dyndns.org","threadId":"31130","inReplyTo":"7vvch6t5in.fsf@alter.siamese.dyndns.org","subject":"[PATCH] Documentation: do not mention .git/refs/* directories","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-08-06T21:04:06Z","receivedAt":"2012-08-06T21:04:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"It is an implementation detail that a new tag is created by adding a\nfile in the .git/refs/tags directory.  The only thing the user needs\nto know is that a \"git tag\" creates a ref in the refs/tags namespace,\nand without \"-f\", it does not overwrite an existing tag.\n\nInspired by a report from 乙酸鋰 <ch3cooli@gmail.com>; I think I\ncaught all the existing mention in Documentation/ directory in the\ntip of 1.7.9.X maintenance track, but we may have added new ones\nsince then.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-describe.txt      |  4 ++--\n Documentation/git-filter-branch.txt |  3 ++-\n Documentation/git-fsck.txt          |  4 ++--\n Documentation/git-lost-found.txt    |  3 ++-\n Documentation/git-pack-refs.txt     | 19 +++++++++++++++----\n Documentation/git-replace.txt       |  5 ++---\n Documentation/git-tag.txt           |  5 ++---\n 7 files changed, 27 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex 039cce2..72d6bb6 100644\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -36,12 +36,12 @@ OPTIONS\n \n --all::\n \tInstead of using only the annotated tags, use any ref\n-\tfound in `.git/refs/`.  This option enables matching\n+\tfound in `refs/` namespace.  This option enables matching\n \tany known branch, remote-tracking branch, or lightweight tag.\n \n --tags::\n \tInstead of using only the annotated tags, use any tag\n-\tfound in `.git/refs/tags`.  This option enables matching\n+\tfound in `refs/tags` namespace.  This option enables matching\n \ta lightweight (non-annotated) tag.\n \n --contains::\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 0f2f117..924a38c 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -32,7 +32,8 @@ changes, which would normally have no effect.  Nevertheless, this may be\n useful in the future for compensating for some git bugs or such,\n therefore such a usage is permitted.\n \n-*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`.\n+*NOTE*: This command honors `.git/info/grafts` file and refs in\n+the `refs/replace/` namespace.\n If you have any grafts or replacement refs defined, running this command\n will make them permanent.\n \ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex 6c47395..df9ea8d 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -23,8 +23,8 @@ OPTIONS\n \tAn object to treat as the head of an unreachability trace.\n +\n If no objects are given, 'git fsck' defaults to using the\n-index file, all SHA1 references in .git/refs/*, and all reflogs (unless\n---no-reflogs is given) as heads.\n+index file, all SHA1 references in `refs` namespace, and all reflogs\n+(unless --no-reflogs is given) as heads.\n \n --unreachable::\n \tPrint out objects that exist but that aren't reachable from any\ndiff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt\nindex c406a11..d549328 100644\n--- a/Documentation/git-lost-found.txt\n+++ b/Documentation/git-lost-found.txt\n@@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*)\n ------------\n \n After making sure you know which the object is the tag you are looking\n-for, you can reconnect it to your regular .git/refs hierarchy.\n+for, you can reconnect it to your regular `refs` hierarchy by using\n+the `update-ref` command.\n \n ------------\n $ git cat-file -t 1ef2b196\ndiff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt\nindex a3c6677..7664bd1 100644\n--- a/Documentation/git-pack-refs.txt\n+++ b/Documentation/git-pack-refs.txt\n@@ -14,7 +14,8 @@ DESCRIPTION\n -----------\n \n Traditionally, tips of branches and tags (collectively known as\n-'refs') were stored one file per ref under `$GIT_DIR/refs`\n+'refs') were stored one file per ref in a (sub)directory\n+under `$GIT_DIR/refs`\n directory.  While many branch tips tend to be updated often,\n most tags and some branch tips are never updated.  When a\n repository has hundreds or thousands of tags, this\n@@ -22,13 +23,14 @@ one-file-per-ref format both wastes storage and hurts\n performance.\n \n This command is used to solve the storage and performance\n-problem by stashing the refs in a single file,\n+problem by storing the refs in a single file,\n `$GIT_DIR/packed-refs`.  When a ref is missing from the\n-traditional `$GIT_DIR/refs` hierarchy, it is looked up in this\n+traditional `$GIT_DIR/refs` directory hierarchy, it is looked\n+up in this\n file and used if found.\n \n Subsequent updates to branches always create new files under\n-`$GIT_DIR/refs` hierarchy.\n+`$GIT_DIR/refs` directory hierarchy.\n \n A recommended practice to deal with a repository with too many\n refs is to pack its refs with `--all --prune` once, and\n@@ -57,6 +59,15 @@ a repository with many branches of historical interests.\n The command usually removes loose refs under `$GIT_DIR/refs`\n hierarchy after packing them.  This option tells it not to.\n \n+\n+BUGS\n+----\n+\n+Older documentation written before the packed-refs mechanism was\n+introduced may still say things like \".git/refs/heads/<branch> file\n+exists\" when it means \"branch <branch> exists\".\n+\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt\nindex 17df525..51131d0 100644\n--- a/Documentation/git-replace.txt\n+++ b/Documentation/git-replace.txt\n@@ -14,14 +14,13 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Adds a 'replace' reference in `.git/refs/replace/`\n+Adds a 'replace' reference in `refs/replace/` namespace.\n \n The name of the 'replace' reference is the SHA1 of the object that is\n replaced. The content of the 'replace' reference is the SHA1 of the\n replacement object.\n \n-Unless `-f` is given, the 'replace' reference must not yet exist in\n-`.git/refs/replace/` directory.\n+Unless `-f` is given, the 'replace' reference must not yet exist.\n \n Replacement references will be used by default by all git commands\n except those doing reachability traversal (prune, pack transfer and\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 53ff5f6..f7abf0b 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -18,11 +18,10 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given\n+Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given\n to delete, list or verify tags.\n \n-Unless `-f` is given, the tag to be created must not yet exist in the\n-`.git/refs/tags/` directory.\n+Unless `-f` is given, the named tag must not yet exist.\n \n If one of `-a`, `-s`, or `-u <key-id>` is passed, the command\n creates a 'tag' object, and requires a tag message.  Unless\n-- \n1.7.12.rc1.78.g77644ce\n"}]}