aboutsummaryrefslogtreecommitdiff
path: root/Documentation/git-pack-refs.txt
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2012-08-06 13:36:47 -0700
committerJunio C Hamano <gitster@pobox.com>2012-08-06 14:04:16 -0700
commit831e61f80fab2d3f9ba1773e657803dcf8b16432 (patch)
tree6ced3d26ab664b5ab3885eaef205e8e0d229c5bf /Documentation/git-pack-refs.txt
parentd0f1ea6003d97e63110fa7d50bb07f546a909b6e (diff)
downloadgit-831e61f80fab2d3f9ba1773e657803dcf8b16432.tar.gz
git-831e61f80fab2d3f9ba1773e657803dcf8b16432.tar.xz
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>
Diffstat (limited to 'Documentation/git-pack-refs.txt')
-rw-r--r--Documentation/git-pack-refs.txt19
1 files changed, 15 insertions, 4 deletions
diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt
index a3c6677bf..7664bd174 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