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@xxxxxxxxx>; 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@xxxxxxxxx> --- 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html