From 831e61f80fab2d3f9ba1773e657803dcf8b16432 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 6 Aug 2012 13:36:47 -0700 Subject: Documentation: do not mention .git/refs/* directories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 乙酸鋰 ; 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 --- Documentation/git-pack-refs.txt | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) (limited to 'Documentation/git-pack-refs.txt') diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index a3c6677bfa..7664bd1741 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/ file +exists" when it means "branch exists". + + GIT --- Part of the linkgit:git[1] suite -- cgit v1.2.3