Re: [PATCH] git-remote.txt: fix wrong remote refspec

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> Obviously correct; thanks.
>
> There is another questionable one you did not touch, though.
>
>     With `-t <branch>` option, instead of the default glob
>     refspec for the remote to track all branches under
>     `$GIT_DIR/remotes/<name>/`, a refspec to track only `<branch>`
>     is created.  You can give more than one `-t <branch>` to track
>     multiple branches without grabbing all branches.
>
> The above says "$GIT_DIR/remotes/<name>/", but it should say
>
>     ... all branches under refs/remotes/<name>/ namespace,...
>
> Also we should try to see if we can come up with a way to say the things
> the part your patch touched describe _without_ mentioning $GIT_DIR at
> all. "Store in $GIT_DIR/refs/$X" talks too much about the implementation
> detail that the ref in question is implemented as a loose ref. We would
> pack it into a single entry in $GIT_DIR/packed-refs file when we run gc,
> and at that point "$GIT_DIR/refs/$X" is no longer a correct description.

And here is my attempt, on top of Namhyung's v2 of this patch.

-- >8 --
Subject: 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>
---
 Documentation/git-remote.txt |   19 ++++++++++---------
 1 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 1e3945f..5a8c506 100644
--- 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
-`$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.
 +
-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
@@ -92,24 +92,25 @@ configuration settings for the remote are removed.
 
 '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`.
 +
-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
-`$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.
 +
-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.
 +