git-remote.txt: avoid sounding as if loose refs are the only ones in the world

It was correct to say "The file $GIT_DIR/refs/heads/master stores the
commit object name at the tip of the master branch" in the older days,
but not anymore, as refs can be packed into $GIT_DIR/packed-refs file.

Update the document to talk in terms of a more abstract concept "ref" and
"symbolic ref" where we are not describing the underlying implementation
detail.

This on purpose leaves two instances of $GIT_DIR/ in the git-remote
documentation; they do talk about $GIT_DIR/remotes/ and $GIT_DIR/branches/
file hierarchy that used to be the place to store configuration around
remotes before the configuration mechanism took them over.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 1e3945f0b0e5562bfc2670548434db43aa0a490c..5a8c5061f3701c57bab75b2b4c70ad620f7e536f 100644 (file)
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -60,11 +60,11 @@ the remote repository.
 +
 With `-t <branch>` option, instead of the default glob
 refspec for the remote to track all branches under
 +
 With `-t <branch>` option, instead of the default glob
 refspec for the remote to track all branches under

-`$GIT_DIR/refs/remotes/<name>/`, a refspec to track only `<branch>`
+the `refs/remotes/<name>/` namespace, a refspec to track only `<branch>`

 is created.  You can give more than one `-t <branch>` to track
 multiple branches without grabbing all branches.
 +
 is created.  You can give more than one `-t <branch>` to track
 multiple branches without grabbing all branches.
 +

-With `-m <master>` option, `$GIT_DIR/refs/remotes/<name>/HEAD` is set
+With `-m <master>` option, a symbolic-ref `refs/remotes/<name>/HEAD` is set

 up to point at remote's `<master>` branch. See also the set-head command.
 +
 When a fetch mirror is created with `\--mirror=fetch`, the refs will not
 up to point at remote's `<master>` branch. See also the set-head command.
 +
 When a fetch mirror is created with `\--mirror=fetch`, the refs will not


@@ -92,24 +92,25 @@ configuration settings for the remote are removed.
 
 'set-head'::
 
 
 'set-head'::
 

-Sets or deletes the default branch (`$GIT_DIR/refs/remotes/<name>/HEAD`) for
+Sets or deletes the default branch (i.e. the target of the
+symbolic-ref `refs/remotes/<name>/HEAD`) for

 the named remote. Having a default branch for a remote is not required,
 but allows the name of the remote to be specified in lieu of a specific
 branch. For example, if the default branch for `origin` is set to
 `master`, then `origin` may be specified wherever you would normally
 specify `origin/master`.
 +
 the named remote. Having a default branch for a remote is not required,
 but allows the name of the remote to be specified in lieu of a specific
 branch. For example, if the default branch for `origin` is set to
 `master`, then `origin` may be specified wherever you would normally
 specify `origin/master`.
 +

-With `-d`, `$GIT_DIR/refs/remotes/<name>/HEAD` is deleted.
+With `-d`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted.

 +
 +

-With `-a`, the remote is queried to determine its `HEAD`, then
-`$GIT_DIR/refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote
+With `-a`, the remote is queried to determine its `HEAD`, then the
+symbolic-ref `refs/remotes/<name>/HEAD` is set to the same branch. e.g., if the remote

 `HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set
 `HEAD` is pointed at `next`, "`git remote set-head origin -a`" will set

-`$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will
+the symbolic-ref `refs/remotes/origin/HEAD` to `refs/remotes/origin/next`. This will

 only work if `refs/remotes/origin/next` already exists; if not it must be
 fetched first.
 +
 only work if `refs/remotes/origin/next` already exists; if not it must be
 fetched first.
 +

-Use `<branch>` to set `$GIT_DIR/refs/remotes/<name>/HEAD` explicitly. e.g., "git
-remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to
+Use `<branch>` to set the symbolic-ref `refs/remotes/<name>/HEAD` explicitly. e.g., "git
+remote set-head origin master" will set the symbolic-ref `refs/remotes/origin/HEAD` to

 `refs/remotes/origin/master`. This will only work if
 `refs/remotes/origin/master` already exists; if not it must be fetched first.
 +
 `refs/remotes/origin/master`. This will only work if
 `refs/remotes/origin/master` already exists; if not it must be fetched first.
 +