Re: [PATCH] git-remote.txt: fix wrong remote refspec
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:51:31
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-06-15 · [PATCH] git-remote.txt: fix wrong remote refspec · Namhyung Kim <hidden>
- 2016-06-15 · Re: [PATCH] git-remote.txt: fix wrong remote refspec · Junio C Hamano <hidden>
- 2016-06-15 · Re: [PATCH] git-remote.txt: fix wrong remote refspec · Namhyung Kim <hidden>
Junio C Hamano [off-list ref] 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 <redacted> --- 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. +