Documentation: do not mention .git/refs/* directories

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>

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 039cce2e98367fdbff6f7c0ea68f8f4f77b8a107..72d6bb612ba8890a7f2a8c3ff13820a53918c74a 100644 (file)
--- 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
 
 --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
        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::
        a lightweight (non-annotated) tag.
 
 --contains::

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 0f2f1173834bdee77bd1d8d77e070af07a7b3580..924a38c96caca8883f10a5cd762749ed5e0e7445 100644 (file)
--- 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.
 
 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.
 
 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 6c47395ad2d22f54ed76dda914efbc28b0dca083..df9ea8df0b9d35103485e4eeb94bcae6c4b27ab5 100644 (file)
--- 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
        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
 
 --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 c406a1100159471cf904629b5d4afc0469c382c0..d54932889f3d5b3c59f403920203911d52227365 100644 (file)
--- 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
 ------------
 
 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
 
 ------------
 $ git cat-file -t 1ef2b196

diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt
index a3c6677bfaaf628410eb85ce06f58d3c2b4df966..7664bd174193db807005833b413013e2f7bceda8 100644 (file)
--- 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
 -----------
 
 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
 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
 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
 `$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
 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
 
 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.
 
 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
 GIT
 ---
 Part of the linkgit:git[1] suite

diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index 17df525275493f5bdcdd912ad56581ffa8a97fa2..51131d0858bf5a7519b8759e2ee081b3b5f27b48 100644 (file)
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -14,14 +14,13 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
 
 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.
 
 
 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
 
 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 53ff5f6cf7b9420933b022accace1355db6337c6..f7abf0bca7046e96b0bef7afbcf4c07c0805a020 100644 (file)
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -18,11 +18,10 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
 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.
 
 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
 
 If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
 creates a 'tag' object, and requires a tag message.  Unless