Merge branch 'jc/tag-doc' into maint-1.7.11

Our documentation used to assume having files in .git/refs/*
directories was the only to have branches and tags, but that is not
true for quite some time.

* jc/tag-doc:
Documentation: do not mention .git/refs/* directories

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
-       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 81f58234a79a94ef5e9b60e1985b096cff6fcb5c..15e7ac80c087eee7d0bf10af5653f421bcbee0dc 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.
 
-*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 bbb25da2dd601cd9ddcdbeae525c82a08fbfde4a..da348fc9427d144335acc9d4d2c20549f850fa32 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
-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 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
-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 10afd4edfe515013bd92ad18d842536a537142a5..f131677478e91f8ab6611a6e45dda56ff48a9e2a 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
-'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 17df525275493f5bdcdd912ad56581ffa8a97fa2..51131d0858bf5a7519b8759e2ee081b3b5f27b48 100644 (file)
--- 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 e36a7c3d1e11e38950c74b32ab4f1ac9a4683a41..247534e908d9f5b804a60b6707d1962eccc9bb1a 100644 (file)
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -20,11 +20,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