git-tag documentation enhancement

git-tag documentation enhancement

[乙酸鋰]

Dear Sir,

I would like to enhance git-tag documentation

--Unless -f is given, the tag to be created must not yet exist in the
.git/refs/tags/ directory.
++Unless -f is given, the tag to be created must not yet exist in the
.git/refs/tags/ directory or inside .git/packed-refs file.

Regards,
ch3cooli

Re: git-tag documentation enhancement

[Junio C Hamano]

乙酸鋰 <ch3cooli@gmail.com> writes:

> I would like to enhance git-tag documentation
>
> --Unless -f is given, the tag to be created must not yet exist in the
> .git/refs/tags/ directory.
> ++Unless -f is given, the tag to be created must not yet exist in the
> .git/refs/tags/ directory or inside .git/packed-refs file.

I think the updated text is technically correct, but I do not think
it is a good direction to go.  The root cause of the problem was
that the original text assumed ".git/refs/tags/ directory" will
forever be the only way to have a local tag, and the description was
left behind when packed refs mechanism was introduced to improve the
file system usage.  It shouldn't have relied its description on such
an implementation detail in the first place.

The updated text still shares the same problem.  I think the right
fix is to say something like this:

        Unless -f is given, the tag to be created must not yet exist
        as a local tag.

[PATCH] Documentation: do not mention .git/refs/* directories

[Junio C Hamano]

It is an implementation detail that a new tag is created by adding a
file in the .git/refs/tags directory.  The only thing the user needs
to know is that a "git tag" creates a ref in the refs/tags namespace,
and without "-f", it does not overwrite an existing tag.

Inspired by a report from 乙酸鋰 <ch3cooli@gmail.com>; I think I
caught all the existing mention in Documentation/ directory in the
tip of 1.7.9.X maintenance track, but we may have added new ones
since then.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-describe.txt      |  4 ++--
 Documentation/git-filter-branch.txt |  3 ++-
 Documentation/git-fsck.txt          |  4 ++--
 Documentation/git-lost-found.txt    |  3 ++-
 Documentation/git-pack-refs.txt     | 19 +++++++++++++++----
 Documentation/git-replace.txt       |  5 ++---
 Documentation/git-tag.txt           |  5 ++---
 7 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 039cce2..72d6bb6 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -36,12 +36,12 @@ OPTIONS
 
 --all::
 	Instead of using only the annotated tags, use any ref
-	found in `.git/refs/`.  This option enables matching
+	found in `refs/` namespace.  This option enables matching
 	any known branch, remote-tracking branch, or lightweight tag.
 
 --tags::
 	Instead of using only the annotated tags, use any tag
-	found in `.git/refs/tags`.  This option enables matching
+	found in `refs/tags` namespace.  This option enables matching
 	a lightweight (non-annotated) tag.
 
 --contains::
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 0f2f117..924a38c 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -32,7 +32,8 @@ changes, which would normally have no effect.  Nevertheless, this may be
 useful in the future for compensating for some git bugs or such,
 therefore such a usage is permitted.
 
-*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`.
+*NOTE*: This command honors `.git/info/grafts` file and refs in
+the `refs/replace/` namespace.
 If you have any grafts or replacement refs defined, running this command
 will make them permanent.
 
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 6c47395..df9ea8d 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -23,8 +23,8 @@ OPTIONS
 	An object to treat as the head of an unreachability trace.
 +
 If no objects are given, 'git fsck' defaults to using the
-index file, all SHA1 references in .git/refs/*, and all reflogs (unless
---no-reflogs is given) as heads.
+index file, all SHA1 references in `refs` namespace, and all reflogs
+(unless --no-reflogs is given) as heads.
 
 --unreachable::
 	Print out objects that exist but that aren't reachable from any
diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt
index c406a11..d549328 100644
--- a/Documentation/git-lost-found.txt
+++ b/Documentation/git-lost-found.txt
@@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*)
 ------------
 
 After making sure you know which the object is the tag you are looking
-for, you can reconnect it to your regular .git/refs hierarchy.
+for, you can reconnect it to your regular `refs` hierarchy by using
+the `update-ref` command.
 
 ------------
 $ git cat-file -t 1ef2b196
diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt
index a3c6677..7664bd1 100644
--- a/Documentation/git-pack-refs.txt
+++ b/Documentation/git-pack-refs.txt
@@ -14,7 +14,8 @@ DESCRIPTION
 -----------
 
 Traditionally, tips of branches and tags (collectively known as
-'refs') were stored one file per ref under `$GIT_DIR/refs`
+'refs') were stored one file per ref in a (sub)directory
+under `$GIT_DIR/refs`
 directory.  While many branch tips tend to be updated often,
 most tags and some branch tips are never updated.  When a
 repository has hundreds or thousands of tags, this
@@ -22,13 +23,14 @@ one-file-per-ref format both wastes storage and hurts
 performance.
 
 This command is used to solve the storage and performance
-problem by stashing the refs in a single file,
+problem by storing the refs in a single file,
 `$GIT_DIR/packed-refs`.  When a ref is missing from the
-traditional `$GIT_DIR/refs` hierarchy, it is looked up in this
+traditional `$GIT_DIR/refs` directory hierarchy, it is looked
+up in this
 file and used if found.
 
 Subsequent updates to branches always create new files under
-`$GIT_DIR/refs` hierarchy.
+`$GIT_DIR/refs` directory hierarchy.
 
 A recommended practice to deal with a repository with too many
 refs is to pack its refs with `--all --prune` once, and
@@ -57,6 +59,15 @@ a repository with many branches of historical interests.
 The command usually removes loose refs under `$GIT_DIR/refs`
 hierarchy after packing them.  This option tells it not to.
 
+
+BUGS
+----
+
+Older documentation written before the packed-refs mechanism was
+introduced may still say things like ".git/refs/heads/<branch> file
+exists" when it means "branch <branch> exists".
+
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index 17df525..51131d0 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -14,14 +14,13 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Adds a 'replace' reference in `.git/refs/replace/`
+Adds a 'replace' reference in `refs/replace/` namespace.
 
 The name of the 'replace' reference is the SHA1 of the object that is
 replaced. The content of the 'replace' reference is the SHA1 of the
 replacement object.
 
-Unless `-f` is given, the 'replace' reference must not yet exist in
-`.git/refs/replace/` directory.
+Unless `-f` is given, the 'replace' reference must not yet exist.
 
 Replacement references will be used by default by all git commands
 except those doing reachability traversal (prune, pack transfer and
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 53ff5f6..f7abf0b 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -18,11 +18,10 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given
+Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
 to delete, list or verify tags.
 
-Unless `-f` is given, the tag to be created must not yet exist in the
-`.git/refs/tags/` directory.
+Unless `-f` is given, the named tag must not yet exist.
 
 If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
 creates a 'tag' object, and requires a tag message.  Unless
-- 
1.7.12.rc1.78.g77644ce