docs: don't talk about $GIT_DIR/refs/ everywhere
It is misleading to say that we pull refs from $GIT_DIR/refs/*, because we may also consult the packed refs mechanism. These days we tend to treat the "refs hierarchy" as more of an abstract namespace that happens to be represented as $GIT_DIR/refs. At best, this is a minor inaccuracy, but at worst it can confuse users who then look in $GIT_DIR/refs and find that it is missing some of the refs they expected to see. This patch drops most uses of "$GIT_DIR/refs/*", changing them into just "refs/*", under the assumption that users can handle the concept of an abstract refs namespace. There are a few things to note: - most cases just dropped the $GIT_DIR/ portion. But for cases where that left _just_ the word "refs", I changed it to "refs/" to help indicate that it was a hierarchy. I didn't do the same for longer paths (e.g., "refs/heads" remained, instead of becoming "refs/heads/"). - in some cases, no change was made, as the text was explicitly about unpacked refs (e.g., the discussion in git-pack-refs). - In some cases it made sense instead to note the existence of packed refs (e.g., in check-ref-format and rev-parse). Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Feb 17, 2010 at 20:16 UTC
cc1b8d8bc6e453b96798574d67ce9590eb3e82e1
10 files changed
+39
-36
Documentation/git-check-ref-format.txt
+3
-2
@@ -19,8 +19,9 @@ status if it is not.
19
20
A reference is used in git to specify branches and tags. A
21
branch head is stored under the `$GIT_DIR/refs/heads` directory, and
22
-a tag is stored under the `$GIT_DIR/refs/tags` directory. git
23
-imposes the following rules on how references are named:
22
+a tag is stored under the `$GIT_DIR/refs/tags` directory (or, if refs
23
+are packed by `git gc`, as entries in the `$GIT_DIR/packed-refs` file).
24
+git imposes the following rules on how references are named:
25
26
. They can include slash `/` for hierarchical (directory)
27
grouping, but no slash-separated component can begin with a
Documentation/git-clone.txt
+1
-1
@@ -29,7 +29,7 @@ arguments will in addition merge the remote master branch into the
29
current master branch, if any.
30
31
This default configuration is achieved by creating references to
32
-the remote branch heads under `$GIT_DIR/refs/remotes/origin` and
32
+the remote branch heads under `refs/remotes/origin` and
33
by initializing `remote.origin.url` and `remote.origin.fetch`
34
configuration variables.
35
Documentation/git-fetch-pack.txt
+1
-1
@@ -18,7 +18,7 @@ higher level wrapper of this command, instead.
18
Invokes 'git-upload-pack' on a possibly remote repository
19
and asks it to send objects missing from this repository, to
20
update the named heads. The list of commits available locally
21
-is found out by scanning local $GIT_DIR/refs/ and sent to
21
+is found out by scanning the local refs/ hierarchy and sent to
22
'git-upload-pack' running on the other end.
23
24
This command degenerates to download everything to complete the
Documentation/git-pack-objects.txt
+1
-1
@@ -73,7 +73,7 @@ base-name::
73
--all::
74
This implies `--revs`. In addition to the list of
75
revision arguments read from the standard input, pretend
76
- as if all refs under `$GIT_DIR/refs` are specified to be
76
+ as if all refs under `refs/` are specified to be
77
included.
78
79
--include-tag::
Documentation/git-prune.txt
+1
-1
@@ -17,7 +17,7 @@ NOTE: In most cases, users should run 'git gc', which calls
17
'git prune'. See the section "NOTES", below.
18
19
This runs 'git fsck --unreachable' using all the refs
20
-available in `$GIT_DIR/refs`, optionally with additional set of
20
+available in `refs/`, optionally with additional set of
21
objects specified on the command line, and prunes all unpacked
22
objects unreachable from any of these head objects from the object database.
23
In addition, it
Documentation/git-push.txt
+3
-3
@@ -69,11 +69,11 @@ nor in any Push line of the corresponding remotes file---see below).
69
70
--all::
71
Instead of naming each ref to push, specifies that all
72
- refs under `$GIT_DIR/refs/heads/` be pushed.
72
+ refs under `refs/heads/` be pushed.
73
74
--mirror::
75
Instead of naming each ref to push, specifies that all
76
- refs under `$GIT_DIR/refs/` (which includes but is not
76
+ refs under `refs/` (which includes but is not
77
limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
78
be mirrored to the remote repository. Newly created local
79
refs will be pushed to the remote end, locally updated refs
@@ -96,7 +96,7 @@ nor in any Push line of the corresponding remotes file---see below).
96
the same as prefixing all refs with a colon.
97
98
--tags::
99
- All refs under `$GIT_DIR/refs/tags` are pushed, in
99
+ All refs under `refs/tags` are pushed, in
100
addition to refspecs explicitly listed on the command
101
line.
102
Documentation/git-rev-parse.txt
+12
-10
@@ -101,15 +101,14 @@ OPTIONS
101
abbreviation mode.
102
103
--all::
104
- Show all refs found in `$GIT_DIR/refs`.
104
+ Show all refs found in `refs/`.
105
106
--branches[=pattern]::
107
--tags[=pattern]::
108
--remotes[=pattern]::
109
Show all branches, tags, or remote-tracking branches,
110
- respectively (i.e., refs found in `$GIT_DIR/refs/heads`,
111
- `$GIT_DIR/refs/tags`, or `$GIT_DIR/refs/remotes`,
112
- respectively).
110
+ respectively (i.e., refs found in `refs/heads`,
111
+ `refs/tags`, or `refs/remotes`, respectively).
112
+
113
If a `pattern` is given, only refs matching the given shell glob are
114
shown. If the pattern does not contain a globbing character (`?`,
@@ -189,7 +188,7 @@ blobs contained in a commit.
188
`g`, and an abbreviated object name.
189
190
* A symbolic ref name. E.g. 'master' typically means the commit
192
- object referenced by $GIT_DIR/refs/heads/master. If you
191
+ object referenced by refs/heads/master. If you
192
happen to have both heads/master and tags/master, you can
193
explicitly say 'heads/master' to tell git which one you mean.
194
When ambiguous, a `<name>` is disambiguated by taking the
@@ -198,15 +197,15 @@ blobs contained in a commit.
197
. if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
198
useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
199
201
- . otherwise, `$GIT_DIR/refs/<name>` if exists;
200
+ . otherwise, `refs/<name>` if exists;
201
203
- . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
202
+ . otherwise, `refs/tags/<name>` if exists;
203
205
- . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
204
+ . otherwise, `refs/heads/<name>` if exists;
205
207
- . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
206
+ . otherwise, `refs/remotes/<name>` if exists;
207
209
- . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
208
+ . otherwise, `refs/remotes/<name>/HEAD` if exists.
209
+
210
HEAD names the commit your changes in the working tree is based on.
211
FETCH_HEAD records the branch you fetched from a remote repository
@@ -217,6 +216,9 @@ you can change the tip of the branch back to the state before you ran
216
them easily.
217
MERGE_HEAD records the commit(s) you are merging into your branch
218
when you run 'git merge'.
219
++
220
+Note that any of the `refs/*` cases above may come either from
221
+the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
222
223
* A ref followed by the suffix '@' with a date specification
224
enclosed in a brace
Documentation/git-show-branch.txt
+5
-5
@@ -20,8 +20,8 @@ DESCRIPTION
20
-----------
21
22
Shows the commit ancestry graph starting from the commits named
23
-with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads
24
-and/or $GIT_DIR/refs/tags) semi-visually.
23
+with <rev>s or <globs>s (or all refs under refs/heads
24
+and/or refs/tags) semi-visually.
25
26
It cannot show more than 29 branches and commits at a time.
27
@@ -37,8 +37,8 @@ OPTIONS
37
38
<glob>::
39
A glob pattern that matches branch or tag names under
40
- $GIT_DIR/refs. For example, if you have many topic
41
- branches under $GIT_DIR/refs/heads/topic, giving
40
+ refs/. For example, if you have many topic
41
+ branches under refs/heads/topic, giving
42
`topic/*` would show all of them.
43
44
-r::
@@ -176,7 +176,7 @@ EXAMPLE
176
-------
177
178
If you keep your primary branches immediately under
179
-`$GIT_DIR/refs/heads`, and topic branches in subdirectories of
179
+`refs/heads`, and topic branches in subdirectories of
180
it, having the following in the configuration file may help:
181
182
------------
Documentation/git-stash.txt
+1
-1
@@ -33,7 +33,7 @@ A stash is by default listed as "WIP on 'branchname' ...", but
33
you can give a more descriptive message on the command line when
34
you create one.
35
36
-The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
36
+The latest stash you created is stored in `refs/stash`; older
37
stashes are found in the reflog of this reference and can be named using
38
the usual reflog syntax (e.g. `stash@\{0}` is the most recently
39
created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}`
Documentation/rev-list-options.txt
+11
-11
@@ -225,26 +225,26 @@ endif::git-rev-list[]
225
226
--all::
227
228
- Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
228
+ Pretend as if all the refs in `refs/` are listed on the
229
command line as '<commit>'.
230
231
--branches[=pattern]::
232
233
- Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed
233
+ Pretend as if all the refs in `refs/heads` are listed
234
on the command line as '<commit>'. If `pattern` is given, limit
235
branches to ones matching given shell glob. If pattern lacks '?',
236
'*', or '[', '/*' at the end is implied.
237
238
--tags[=pattern]::
239
240
- Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed
240
+ Pretend as if all the refs in `refs/tags` are listed
241
on the command line as '<commit>'. If `pattern` is given, limit
242
tags to ones matching given shell glob. If pattern lacks '?', '*',
243
or '[', '/*' at the end is implied.
244
245
--remotes[=pattern]::
246
247
- Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed
247
+ Pretend as if all the refs in `refs/remotes` are listed
248
on the command line as '<commit>'. If `pattern`is given, limit
249
remote tracking branches to ones matching given shell glob.
250
If pattern lacks '?', '*', or '[', '/*' at the end is implied.
@@ -259,9 +259,9 @@ endif::git-rev-list[]
259
ifndef::git-rev-list[]
260
--bisect::
261
262
- Pretend as if the bad bisection ref `$GIT_DIR/refs/bisect/bad`
262
+ Pretend as if the bad bisection ref `refs/bisect/bad`
263
was listed and as if it was followed by `--not` and the good
264
- bisection refs `$GIT_DIR/refs/bisect/good-*` on the command
264
+ bisection refs `refs/bisect/good-*` on the command
265
line.
266
endif::git-rev-list[]
267
@@ -561,10 +561,10 @@ Bisection Helpers
561
562
Limit output to the one commit object which is roughly halfway between
563
included and excluded commits. Note that the bad bisection ref
564
-`$GIT_DIR/refs/bisect/bad` is added to the included commits (if it
565
-exists) and the good bisection refs `$GIT_DIR/refs/bisect/good-*` are
564
+`refs/bisect/bad` is added to the included commits (if it
565
+exists) and the good bisection refs `refs/bisect/good-*` are
566
added to the excluded commits (if they exist). Thus, supposing there
567
-are no refs in `$GIT_DIR/refs/bisect/`, if
567
+are no refs in `refs/bisect/`, if
568
569
-----------------------------------------------------------------------
570
$ git rev-list --bisect foo ^bar ^baz
@@ -585,7 +585,7 @@ one.
585
--bisect-vars::
586
587
This calculates the same as `--bisect`, except that refs in
588
-`$GIT_DIR/refs/bisect/` are not used, and except that this outputs
588
+`refs/bisect/` are not used, and except that this outputs
589
text ready to be eval'ed by the shell. These lines will assign the
590
name of the midpoint revision to the variable `bisect_rev`, and the
591
expected number of commits to be tested after `bisect_rev` is tested
@@ -599,7 +599,7 @@ number of commits to be tested if `bisect_rev` turns out to be bad to
599
600
This outputs all the commit objects between the included and excluded
601
commits, ordered by their distance to the included and excluded
602
-commits. Refs in `$GIT_DIR/refs/bisect/` are not used. The farthest
602
+commits. Refs in `refs/bisect/` are not used. The farthest
603
from them is displayed first. (This is the only one displayed by
604
`--bisect`.)
605
+