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

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.
 +

2011-06-23 (목), 08:33 -0700, Junio C Hamano:

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>

By quick grep-ing $GIT_DIR/refs/, I found git.txt and
glossary-content.txt might need the same treatment. Did/Could you check
out those too?

Otherwise, looks good to me.
Thanks.


-- 
Regards,
Namhyung Kim

It is an unimportant implementation detail that branches and tags are
stored somewhere under $GIT_DIR/refs directory. What is more important
is that branches live in refs/heads and tags live in refs/tags hierarchy
in the ref namespace.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/git-check-ref-format.txt |    9 ++++++---
 1 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index 205d83d..61471cf 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt

@@ -18,9 +18,12 @@ Checks if a given 'refname' is acceptable, and exits with a non-zero
 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 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).
+branch head is stored in the `refs/heads` hierarchy while
+a tag is stored in the `refs/tags` hierarchy of the ref namespace
+(which are found in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags`
+directories 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)

-- 
1.7.6.rc3

So here is a miniseries to update various parts of the documentation
that still talk about $GIT_DIR/refs/. They are split into small and
non-overlapping pieces so that any of them can be discarded more or
less independently.

Thanks in advance for comments.

Junio C Hamano (5):
  check-ref-format doc: de-emphasize the implementation detail of a ref
  git.txt: de-emphasize the implementation detail of a ref
  glossary: update description of "tag"
  glossary: update description of head and ref
  glossary: clarify description of HEAD

 Documentation/git-check-ref-format.txt |    9 ++++++---
 Documentation/git.txt                  |    7 +++----
 Documentation/glossary-content.txt     |   27 ++++++++++++++-------------
 3 files changed, 23 insertions(+), 20 deletions(-)

-- 
1.7.6.rc3

It is an unimportant implementation detail that ref namespaces are
implemented as subdirectories of $GIT_DIR/refs. What is more important
is that tags are in refs/tags hierarchy in the ref namespace.

Also note that a tag can point at an object of arbitrary type, not limited
to commit.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/glossary-content.txt |   16 ++++++++--------
 1 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 33716a3..c437f34 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt

@@ -427,14 +427,14 @@ including Documentation/chapter_1/figure_1.jpg.
 	command.
 
 [[def_tag]]tag::
-	A <<def_ref,ref>> pointing to a <<def_tag_object,tag>> or
-	<<def_commit_object,commit object>>. In contrast to a <<def_head,head>>,
-	a tag is not changed by a <<def_commit,commit>>. Tags (not
-	<<def_tag_object,tag objects>>) are stored in `$GIT_DIR/refs/tags/`. A
-	git tag has nothing to do with a Lisp tag (which would be
-	called an <<def_object_type,object type>> in git's context). A
-	tag is most typically used to mark a particular point in the
-	commit ancestry <<def_chain,chain>>.
+	A <<def_ref,ref>> under `refs/tags/` namespace that points to an
+	object of an arbitrary type (typically a tag points to either a
+	<<def_tag_object,tag>> or a <<def_commit_object,commit object>>).
+	In contrast to a <<def_head,head>>, a tag is not updated by
+	 the `commit` command. A git tag has nothing to do with	a Lisp
+	tag (which would be called an <<def_object_type,object type>>
+	in git's context). A tag is most typically used to mark a particular
+	point in the commit ancestry <<def_chain,chain>>.
 
 [[def_tag_object]]tag object::
 	An <<def_object,object>> containing a <<def_ref,ref>> pointing to

-- 
1.7.6.rc3

It is an unimportant implementation detail that branches and tags are
stored somewhere under $GIT_DIR/refs directory, or the name of the commit
that will become the parent of the next commit is stored in $GIT_DIR/HEAD.

What is more important is that branches live in refs/heads and tags live
in refs/tags hierarchy in the ref namespace, and HEAD means the tip of the
current branch.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/git.txt |    7 +++----
 1 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 8c0bfdf..7fc6b88 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt

@@ -510,16 +510,15 @@ Any git command accepting any <object> can also use the following
 symbolic notation:
 
 HEAD::
-	indicates the head of the current branch (i.e. the
-	contents of `$GIT_DIR/HEAD`).
+	indicates the head of the current branch.
 
 <tag>::
 	a valid tag 'name'
-	(i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
+	(i.e. a `refs/tags/<tag>` reference).
 
 <head>::
 	a valid head 'name'
-	(i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
+	(i.e. a `refs/heads/<head>` reference).
 
 For a more complete list of ways to spell object names, see
 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].

-- 
1.7.6.rc3

Reword them to avoid sounding as if loose refs are the only ones in the world.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/glossary-content.txt |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index c437f34..dd690bd 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt

@@ -161,8 +161,8 @@ to point at the new commit.
 
 [[def_head]]head::
 	A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a
-	<<def_branch,branch>>.  Heads are stored in
-	`$GIT_DIR/refs/heads/`, except when using packed refs. (See
+	<<def_branch,branch>>.  Heads are stored in a file in
+	`$GIT_DIR/refs/heads/` directory, except when using packed refs. (See
 	linkgit:git-pack-refs[1].)
 
 [[def_HEAD]]HEAD::

@@ -350,8 +350,9 @@ including Documentation/chapter_1/figure_1.jpg.
 
 [[def_ref]]ref::
 	A 40-byte hex representation of a <<def_SHA1,SHA1>> or a name that
-	denotes a particular <<def_object,object>>. These may be stored in
-	`$GIT_DIR/refs/`.
+	denotes a particular <<def_object,object>>. They may be stored in
+	a file under `$GIT_DIR/refs/` directory, or
+	in the `$GIT_DIR/packed-refs` file.
 
 [[def_reflog]]reflog::
 	A reflog shows the local "history" of a ref.  In other words,

-- 
1.7.6.rc3

HEAD on a branch does reference a commit via the branch ref it refers to.
The main difference of a detached HEAD is that it _directly_ refers to
a commit.  Clarify this.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/glossary-content.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index dd690bd..f79da21 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt

@@ -170,7 +170,7 @@ to point at the new commit.
 	working tree>> is normally derived from the state of the tree
 	referred to by HEAD.  HEAD is a reference to one of the
 	<<def_head,heads>> in your repository, except when using a
-	<<def_detached_HEAD,detached HEAD>>, in which case it may
+	<<def_detached_HEAD,detached HEAD>>, in which case it may directly
 	reference an arbitrary commit.
 
 [[def_head_ref]]head ref::

-- 
1.7.6.rc3

On Thu, Jun 23, 2011 at 09:52:38AM -0700, Junio C Hamano wrote:

Why "may"? As I understand it, in detached HEAD, it /does/ point
directly to a commit

 	reference an arbitrary commit.
 
 [[def_head_ref]]head ref::

Cheers,
   cmn
-- 
Carlos Martín Nieto | http://cmartin.tk

"¿Cómo voy a decir bobadas si soy mudo?" -- CACHAI

On 6/23/2011 12:52 PM, Junio C Hamano wrote:

  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 (or, if refs
-are packed by `git gc`, as entries in the `$GIT_DIR/packed-refs` file).
+branch head is stored in the `refs/heads` hierarchy while

s/hierarchy while/hierarchy, while/

+a tag is stored in the `refs/tags` hierarchy of the ref namespace
+(which are found in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags`
+directories or, if refs are packed by `git gc`, as entries in
+the `$GIT_DIR/packed-refs` file).

Grammatical complexity of parenthetical comment makes it a bit difficult 
to read. Perhaps simplify as:

   (typically in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags`
   directories, or as entries in file `$GIT_DIR/packed-refs`
   if refs are packed by `git gc`).

-- ES

On 6/23/2011 12:52 PM, Junio C Hamano wrote:

+	In contrast to a<<def_head,head>>, a tag is not updated by
+	 the `commit` command. A git tag has nothing to do with	a Lisp

Line begins with tab+space but you probably want only tab. "with" and 
"a" are separated by a tab but likely ought to be separated by a space.

s/^\t /\t/
s/with\ta/with a/

-- ES