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>

diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index e1c4320f02747cd8681c03f52ea22d64290d96ca..379eee6734323ee566480d5f9159dd28ed27ecd2 100644 (file)
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -19,8 +19,9 @@ status if it is not.
 
 A reference is used in git to specify branches and tags.  A
 branch head is stored under the `$GIT_DIR/refs/heads` directory, and
 
 A reference is used in git to specify branches and tags.  A
 branch head is stored under the `$GIT_DIR/refs/heads` directory, and

-a tag is stored under the `$GIT_DIR/refs/tags` directory.  git
-imposes the following rules on how references are named:
+a tag is stored under the `$GIT_DIR/refs/tags` directory (or, if refs
+are packed by `git gc`, as entries in the `$GIT_DIR/packed-refs` file).
+git imposes the following rules on how references are named:

 
 . They can include slash `/` for hierarchical (directory)
   grouping, but no slash-separated component can begin with a
 
 . They can include slash `/` for hierarchical (directory)
   grouping, but no slash-separated component can begin with a

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index f43c8b2c08ab4ca45f759369dc3d8e85c9f76415..88ea6246a108ade16641c3ebe8688272fb361588 100644 (file)
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -29,7 +29,7 @@ arguments will in addition merge the remote master branch into the
 current master branch, if any.
 
 This default configuration is achieved by creating references to
 current master branch, if any.
 
 This default configuration is achieved by creating references to

-the remote branch heads under `$GIT_DIR/refs/remotes/origin` and
+the remote branch heads under `refs/remotes/origin` and

 by initializing `remote.origin.url` and `remote.origin.fetch`
 configuration variables.
 
 by initializing `remote.origin.url` and `remote.origin.fetch`
 configuration variables.
 

diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index e9952e82108d3a0fa209bc9d720fa1f1229310b4..97ea7973a0839eacf74f2f5bd1ca6a17670c7a8b 100644 (file)
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -18,7 +18,7 @@ higher level wrapper of this command, instead.
 Invokes 'git-upload-pack' on a possibly remote repository
 and asks it to send objects missing from this repository, to
 update the named heads.  The list of commits available locally
 Invokes 'git-upload-pack' on a possibly remote repository
 and asks it to send objects missing from this repository, to
 update the named heads.  The list of commits available locally

-is found out by scanning local $GIT_DIR/refs/ and sent to
+is found out by scanning the local refs/ hierarchy and sent to

 'git-upload-pack' running on the other end.
 
 This command degenerates to download everything to complete the
 'git-upload-pack' running on the other end.
 
 This command degenerates to download everything to complete the

diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index ffd5025f7bdf68b8285f2c98c2c1b37c551e2cb4..61fd7d09982255aa0488555a54256fc3f03c76e4 100644 (file)
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -73,7 +73,7 @@ base-name::
 --all::
        This implies `--revs`.  In addition to the list of
        revision arguments read from the standard input, pretend
 --all::
        This implies `--revs`.  In addition to the list of
        revision arguments read from the standard input, pretend

-       as if all refs under `$GIT_DIR/refs` are specified to be
+       as if all refs under `refs/` are specified to be

        included.
 
 --include-tag::
        included.
 
 --include-tag::

diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt
index 3bb7304517ea3adfd2b5b89b5e75f9d830e57aff..15cfb7a8dc8e5e6eb25ee58b8fe15d89ad62dc8a 100644 (file)
--- a/Documentation/git-prune.txt
+++ b/Documentation/git-prune.txt
@@ -17,7 +17,7 @@ NOTE: In most cases, users should run 'git gc', which calls
 'git prune'. See the section "NOTES", below.
 
 This runs 'git fsck --unreachable' using all the refs
 'git prune'. See the section "NOTES", below.
 
 This runs 'git fsck --unreachable' using all the refs

-available in `$GIT_DIR/refs`, optionally with additional set of
+available in `refs/`, optionally with additional set of

 objects specified on the command line, and prunes all unpacked
 objects unreachable from any of these head objects from the object database.
 In addition, it
 objects specified on the command line, and prunes all unpacked
 objects unreachable from any of these head objects from the object database.
 In addition, it

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index bd79119dd36092f7b31c156a2ca72c7969cd7586..3f103ccb00b10bb4472b82feae32e0e0a5e80fc2 100644 (file)
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -69,11 +69,11 @@ nor in any Push line of the corresponding remotes file---see below).
 
 --all::
        Instead of naming each ref to push, specifies that all
 
 --all::
        Instead of naming each ref to push, specifies that all

-       refs under `$GIT_DIR/refs/heads/` be pushed.
+       refs under `refs/heads/` be pushed.

 
 --mirror::
        Instead of naming each ref to push, specifies that all
 
 --mirror::
        Instead of naming each ref to push, specifies that all

-       refs under `$GIT_DIR/refs/` (which includes but is not
+       refs under `refs/` (which includes but is not

        limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
        be mirrored to the remote repository.  Newly created local
        refs will be pushed to the remote end, locally updated refs
        limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
        be mirrored to the remote repository.  Newly created local
        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).
        the same as prefixing all refs with a colon.
 
 --tags::
        the same as prefixing all refs with a colon.
 
 --tags::

-       All refs under `$GIT_DIR/refs/tags` are pushed, in
+       All refs under `refs/tags` are pushed, in

        addition to refspecs explicitly listed on the command
        line.
 
        addition to refspecs explicitly listed on the command
        line.
 

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index d677c72d5ea6a8d38cf77f663e6b5da591028efa..1a613aa108d649c199c30d0d8a29623243631a7c 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -101,15 +101,14 @@ OPTIONS
        abbreviation mode.
 
 --all::
        abbreviation mode.
 
 --all::

-       Show all refs found in `$GIT_DIR/refs`.
+       Show all refs found in `refs/`.

 
 --branches[=pattern]::
 --tags[=pattern]::
 --remotes[=pattern]::
        Show all branches, tags, or remote-tracking branches,
 
 --branches[=pattern]::
 --tags[=pattern]::
 --remotes[=pattern]::
        Show all branches, tags, or remote-tracking branches,

-       respectively (i.e., refs found in `$GIT_DIR/refs/heads`,
-       `$GIT_DIR/refs/tags`, or `$GIT_DIR/refs/remotes`,
-       respectively).
+       respectively (i.e., refs found in `refs/heads`,
+       `refs/tags`, or `refs/remotes`, respectively).

 +
 If a `pattern` is given, only refs matching the given shell glob are
 shown.  If the pattern does not contain a globbing character (`?`,
 +
 If a `pattern` is given, only refs matching the given shell glob are
 shown.  If the pattern does not contain a globbing character (`?`,


@@ -189,7 +188,7 @@ blobs contained in a commit.
   `g`, and an abbreviated object name.
 
 * A symbolic ref name.  E.g. 'master' typically means the commit
   `g`, and an abbreviated object name.
 
 * A symbolic ref name.  E.g. 'master' typically means the commit

-  object referenced by $GIT_DIR/refs/heads/master.  If you
+  object referenced by refs/heads/master.  If you

   happen to have both heads/master and tags/master, you can
   explicitly say 'heads/master' to tell git which one you mean.
   When ambiguous, a `<name>` is disambiguated by taking the
   happen to have both heads/master and tags/master, you can
   explicitly say 'heads/master' to tell git which one you mean.
   When ambiguous, a `<name>` is disambiguated by taking the


@@ -198,15 +197,15 @@ blobs contained in a commit.
   . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
     useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
 
   . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
     useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
 

-  . otherwise, `$GIT_DIR/refs/<name>` if exists;
+  . otherwise, `refs/<name>` if exists;

 
 

-  . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
+  . otherwise, `refs/tags/<name>` if exists;

 
 

-  . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
+  . otherwise, `refs/heads/<name>` if exists;

 
 

-  . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
+  . otherwise, `refs/remotes/<name>` if exists;

 
 

-  . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
+  . otherwise, `refs/remotes/<name>/HEAD` if exists.

 +
 HEAD names the commit your changes in the working tree is based on.
 FETCH_HEAD records the branch you fetched from a remote repository
 +
 HEAD names the commit your changes in the working tree is based on.
 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
 them easily.
 MERGE_HEAD records the commit(s) you are merging into your branch
 when you run 'git merge'.
 them easily.
 MERGE_HEAD records the commit(s) you are merging into your branch
 when you run 'git merge'.

++
+Note that any of the `refs/*` cases above may come either from
+the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.

 
 * A ref followed by the suffix '@' with a date specification
   enclosed in a brace
 
 * A ref followed by the suffix '@' with a date specification
   enclosed in a brace

diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 734336119c6b1f7ea8241f0404eaa3ba2ae10f69..b9c4154e7332fa59b370ce5be823a9cb6384227c 100644 (file)
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -20,8 +20,8 @@ DESCRIPTION
 -----------
 
 Shows the commit ancestry graph starting from the commits named
 -----------
 
 Shows the commit ancestry graph starting from the commits named

-with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads
-and/or $GIT_DIR/refs/tags) semi-visually.
+with <rev>s or <globs>s (or all refs under refs/heads
+and/or refs/tags) semi-visually.

 
 It cannot show more than 29 branches and commits at a time.
 
 
 It cannot show more than 29 branches and commits at a time.
 


@@ -37,8 +37,8 @@ OPTIONS
 
 <glob>::
        A glob pattern that matches branch or tag names under
 
 <glob>::
        A glob pattern that matches branch or tag names under

-       $GIT_DIR/refs.  For example, if you have many topic
-       branches under $GIT_DIR/refs/heads/topic, giving
+       refs/.  For example, if you have many topic
+       branches under refs/heads/topic, giving

        `topic/*` would show all of them.
 
 -r::
        `topic/*` would show all of them.
 
 -r::


@@ -176,7 +176,7 @@ EXAMPLE
 -------
 
 If you keep your primary branches immediately under
 -------
 
 If you keep your primary branches immediately under

-`$GIT_DIR/refs/heads`, and topic branches in subdirectories of
+`refs/heads`, and topic branches in subdirectories of

 it, having the following in the configuration file may help:
 
 ------------
 it, having the following in the configuration file may help:
 
 ------------

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 84e555d81d9bdd25afeacf868f55a6a868773cd0..473889a660402f5f88b45c6aa3d00d0e85004389 100644 (file)
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -33,7 +33,7 @@ A stash is by default listed as "WIP on 'branchname' ...", but
 you can give a more descriptive message on the command line when
 you create one.
 
 you can give a more descriptive message on the command line when
 you create one.
 

-The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
+The latest stash you created is stored in `refs/stash`; older

 stashes are found in the reflog of this reference and can be named using
 the usual reflog syntax (e.g. `stash@\{0}` is the most recently
 created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}`
 stashes are found in the reflog of this reference and can be named using
 the usual reflog syntax (e.g. `stash@\{0}` is the most recently
 created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}`

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 6e9baf8b38be5fba5e3c82e617ab95d579731884..81c0e6f18498ae72e52e7c7ac0b55429143fabf1 100644 (file)
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -225,26 +225,26 @@ endif::git-rev-list[]
 
 --all::
 
 
 --all::
 

-       Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
+       Pretend as if all the refs in `refs/` are listed on the

        command line as '<commit>'.
 
 --branches[=pattern]::
 
        command line as '<commit>'.
 
 --branches[=pattern]::
 

-       Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed
+       Pretend as if all the refs in `refs/heads` are listed

        on the command line as '<commit>'. If `pattern` is given, limit
        branches to ones matching given shell glob. If pattern lacks '?',
        '*', or '[', '/*' at the end is implied.
 
 --tags[=pattern]::
 
        on the command line as '<commit>'. If `pattern` is given, limit
        branches to ones matching given shell glob. If pattern lacks '?',
        '*', or '[', '/*' at the end is implied.
 
 --tags[=pattern]::
 

-       Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed
+       Pretend as if all the refs in `refs/tags` are listed

        on the command line as '<commit>'. If `pattern` is given, limit
        tags to ones matching given shell glob. If pattern lacks '?', '*',
        or '[', '/*' at the end is implied.
 
 --remotes[=pattern]::
 
        on the command line as '<commit>'. If `pattern` is given, limit
        tags to ones matching given shell glob. If pattern lacks '?', '*',
        or '[', '/*' at the end is implied.
 
 --remotes[=pattern]::
 

-       Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed
+       Pretend as if all the refs in `refs/remotes` are listed

        on the command line as '<commit>'. If `pattern`is given, limit
        remote tracking branches to ones matching given shell glob.
        If pattern lacks '?', '*', or '[', '/*' at the end is implied.
        on the command line as '<commit>'. If `pattern`is given, limit
        remote tracking branches to ones matching given shell glob.
        If pattern lacks '?', '*', or '[', '/*' at the end is implied.


@@ -259,9 +259,9 @@ endif::git-rev-list[]
 ifndef::git-rev-list[]
 --bisect::
 
 ifndef::git-rev-list[]
 --bisect::
 

-       Pretend as if the bad bisection ref `$GIT_DIR/refs/bisect/bad`
+       Pretend as if the bad bisection ref `refs/bisect/bad`

        was listed and as if it was followed by `--not` and the good
        was listed and as if it was followed by `--not` and the good

-       bisection refs `$GIT_DIR/refs/bisect/good-*` on the command
+       bisection refs `refs/bisect/good-*` on the command

        line.
 endif::git-rev-list[]
 
        line.
 endif::git-rev-list[]
 


@@ -561,10 +561,10 @@ Bisection Helpers
 
 Limit output to the one commit object which is roughly halfway between
 included and excluded commits. Note that the bad bisection ref
 
 Limit output to the one commit object which is roughly halfway between
 included and excluded commits. Note that the bad bisection ref

-`$GIT_DIR/refs/bisect/bad` is added to the included commits (if it
-exists) and the good bisection refs `$GIT_DIR/refs/bisect/good-*` are
+`refs/bisect/bad` is added to the included commits (if it
+exists) and the good bisection refs `refs/bisect/good-*` are

 added to the excluded commits (if they exist). Thus, supposing there
 added to the excluded commits (if they exist). Thus, supposing there

-are no refs in `$GIT_DIR/refs/bisect/`, if
+are no refs in `refs/bisect/`, if

 
 -----------------------------------------------------------------------
        $ git rev-list --bisect foo ^bar ^baz
 
 -----------------------------------------------------------------------
        $ git rev-list --bisect foo ^bar ^baz


@@ -585,7 +585,7 @@ one.
 --bisect-vars::
 
 This calculates the same as `--bisect`, except that refs in
 --bisect-vars::
 
 This calculates the same as `--bisect`, except that refs in

-`$GIT_DIR/refs/bisect/` are not used, and except that this outputs
+`refs/bisect/` are not used, and except that this outputs

 text ready to be eval'ed by the shell. These lines will assign the
 name of the midpoint revision to the variable `bisect_rev`, and the
 expected number of commits to be tested after `bisect_rev` is tested
 text ready to be eval'ed by the shell. These lines will assign the
 name of the midpoint revision to the variable `bisect_rev`, and the
 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
 
 This outputs all the commit objects between the included and excluded
 commits, ordered by their distance to the included and excluded
 
 This outputs all the commit objects between the included and excluded
 commits, ordered by their distance to the included and excluded

-commits. Refs in `$GIT_DIR/refs/bisect/` are not used. The farthest
+commits. Refs in `refs/bisect/` are not used. The farthest

 from them is displayed first. (This is the only one displayed by
 `--bisect`.)
 +
 from them is displayed first. (This is the only one displayed by
 `--bisect`.)
 +