@matheusbsbs / matheus-bagliano / commits / 831e61f80f

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>

Junio C Hamano committed Aug 6, 2012 at 13:36 UTC 831e61f80fab2d3f9ba1773e657803dcf8b16432
7 files changed +27 -16
Documentation/git-describe.txt
+2 -2
@@ -36,12 +36,12 @@ OPTIONS
36
37 --all::
38 Instead of using only the annotated tags, use any ref
39 - found in `.git/refs/`. This option enables matching
39 + found in `refs/` namespace. This option enables matching
40 any known branch, remote-tracking branch, or lightweight tag.
41
42 --tags::
43 Instead of using only the annotated tags, use any tag
44 - found in `.git/refs/tags`. This option enables matching
44 + found in `refs/tags` namespace. This option enables matching
45 a lightweight (non-annotated) tag.
46
47 --contains::
Documentation/git-filter-branch.txt
+2 -1
@@ -32,7 +32,8 @@ changes, which would normally have no effect. Nevertheless, this may be
32 useful in the future for compensating for some git bugs or such,
33 therefore such a usage is permitted.
34
35 -*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`.
35 +*NOTE*: This command honors `.git/info/grafts` file and refs in
36 +the `refs/replace/` namespace.
37 If you have any grafts or replacement refs defined, running this command
38 will make them permanent.
39
Documentation/git-fsck.txt
+2 -2
@@ -23,8 +23,8 @@ OPTIONS
23 An object to treat as the head of an unreachability trace.
24 +
25 If no objects are given, 'git fsck' defaults to using the
26 -index file, all SHA1 references in .git/refs/*, and all reflogs (unless
27 ---no-reflogs is given) as heads.
26 +index file, all SHA1 references in `refs` namespace, and all reflogs
27 +(unless --no-reflogs is given) as heads.
28
29 --unreachable::
30 Print out objects that exist but that aren't reachable from any
Documentation/git-lost-found.txt
+2 -1
@@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*)
48 ------------
49
50 After making sure you know which the object is the tag you are looking
51 -for, you can reconnect it to your regular .git/refs hierarchy.
51 +for, you can reconnect it to your regular `refs` hierarchy by using
52 +the `update-ref` command.
53
54 ------------
55 $ git cat-file -t 1ef2b196
Documentation/git-pack-refs.txt
+15 -4
@@ -14,7 +14,8 @@ DESCRIPTION
14 -----------
15
16 Traditionally, tips of branches and tags (collectively known as
17 -'refs') were stored one file per ref under `$GIT_DIR/refs`
17 +'refs') were stored one file per ref in a (sub)directory
18 +under `$GIT_DIR/refs`
19 directory. While many branch tips tend to be updated often,
20 most tags and some branch tips are never updated. When a
21 repository has hundreds or thousands of tags, this
@@ -22,13 +23,14 @@ one-file-per-ref format both wastes storage and hurts
23 performance.
24
25 This command is used to solve the storage and performance
25 -problem by stashing the refs in a single file,
26 +problem by storing the refs in a single file,
27 `$GIT_DIR/packed-refs`. When a ref is missing from the
27 -traditional `$GIT_DIR/refs` hierarchy, it is looked up in this
28 +traditional `$GIT_DIR/refs` directory hierarchy, it is looked
29 +up in this
30 file and used if found.
31
32 Subsequent updates to branches always create new files under
31 -`$GIT_DIR/refs` hierarchy.
33 +`$GIT_DIR/refs` directory hierarchy.
34
35 A recommended practice to deal with a repository with too many
36 refs is to pack its refs with `--all --prune` once, and
@@ -57,6 +59,15 @@ a repository with many branches of historical interests.
59 The command usually removes loose refs under `$GIT_DIR/refs`
60 hierarchy after packing them. This option tells it not to.
61
62 +
63 +BUGS
64 +----
65 +
66 +Older documentation written before the packed-refs mechanism was
67 +introduced may still say things like ".git/refs/heads/<branch> file
68 +exists" when it means "branch <branch> exists".
69 +
70 +
71 GIT
72 ---
73 Part of the linkgit:git[1] suite
Documentation/git-replace.txt
+2 -3
@@ -14,14 +14,13 @@ SYNOPSIS
14
15 DESCRIPTION
16 -----------
17 -Adds a 'replace' reference in `.git/refs/replace/`
17 +Adds a 'replace' reference in `refs/replace/` namespace.
18
19 The name of the 'replace' reference is the SHA1 of the object that is
20 replaced. The content of the 'replace' reference is the SHA1 of the
21 replacement object.
22
23 -Unless `-f` is given, the 'replace' reference must not yet exist in
24 -`.git/refs/replace/` directory.
23 +Unless `-f` is given, the 'replace' reference must not yet exist.
24
25 Replacement references will be used by default by all git commands
26 except those doing reachability traversal (prune, pack transfer and
Documentation/git-tag.txt
+2 -3
@@ -18,11 +18,10 @@ SYNOPSIS
18 DESCRIPTION
19 -----------
20
21 -Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given
21 +Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
22 to delete, list or verify tags.
23
24 -Unless `-f` is given, the tag to be created must not yet exist in the
25 -`.git/refs/tags/` directory.
24 +Unless `-f` is given, the named tag must not yet exist.
25
26 If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
27 creates a 'tag' object, and requires a tag message. Unless