[PATCH 0/3] Some small fixes to glossary-content.txt

[PATCH 0/3] Some small fixes to glossary-content.txt

[Thomas Ackermann]

While proof-reading the user-manual I noticed some issues with glossary-content.txt:

- There is some outdated, misleading or irrelevant information which might only confuse
new Git users and should therefore be removed.
- The entries for object, object name and SHA1 lacked a little bit of consistency.
- The glossary contains partial definitions for refspec and pathspec. The refspec
definition was replaced by a link to the git-push man-page. I also removed the
definition for pathspec but didn't find a single place where pathspecs are defined. 
The glossary surely is the wrong place for a complete definition, but is there something 
missing here or is it sufficient to spread the definition of pathspecs to the relevant man-pages?

[PATCH 1/3] Remove outdated/missleading/irrelevant entries from glossary-content.txt
[PATCH 2/3] Improve description of SHA1 related topics in glossary-content.txt
[PATCH 3/3] Remove definition of refspec and pathspec from glossary-content.txt


---
Thomas

[PATCH 1/3] Remove outdated/missleading/irrelevant entries from glossary-content.txt

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/glossary-content.txt | 28 +++++-----------------------
 1 file changed, 5 insertions(+), 23 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index eb7ba84..ab02238 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -5,7 +5,7 @@
 
 [[def_bare_repository]]bare repository::
 	A bare repository is normally an appropriately
-	named <<def_directory,directory>> with a `.git` suffix that does not
+	named directory with a `.git` suffix that does not
 	have a locally checked-out copy of any of the files under
 	revision control. That is, all of the Git
 	administrative and control files that would normally be present in the
@@ -79,7 +79,7 @@ to point at the new commit.
 	An <<def_object,object>> which contains the information about a
 	particular <<def_revision,revision>>, such as <<def_parent,parents>>, committer,
 	author, date and the <<def_tree_object,tree object>> which corresponds
-	to the top <<def_directory,directory>> of the stored
+	to the top directory of the stored
 	revision.
 
 [[def_core_git]]core Git::
@@ -104,26 +104,11 @@ to point at the new commit.
 	an arbitrary <<def_commit,commit>> that isn't necessarily the tip of any
 	particular branch.  In this case HEAD is said to be "detached".
 
-[[def_dircache]]dircache::
-	You are *waaaaay* behind. See <<def_index,index>>.
-
-[[def_directory]]directory::
-	The list you get with "ls" :-)
-
 [[def_dirty]]dirty::
 	A <<def_working_tree,working tree>> is said to be "dirty" if
 	it contains modifications which have not been <<def_commit,committed>> to the current
 	<<def_branch,branch>>.
 
-[[def_ent]]ent::
-	Favorite synonym to "<<def_tree-ish,tree-ish>>" by some total geeks. See
-	http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth
-	explanation. Avoid this term, not to confuse people.
-
-[[def_evil_merge]]evil merge::
-	An evil merge is a <<def_merge,merge>> that introduces changes that
-	do not appear in any <<def_parent,parent>>.
-
 [[def_fast_forward]]fast-forward::
 	A fast-forward is a special type of <<def_merge,merge>> where you have a
 	<<def_revision,revision>> and you are "merging" another
@@ -257,8 +242,7 @@ This commit is referred to as a "merge commit", or sometimes just a
 	<<def_object,object>>.
 
 [[def_octopus]]octopus::
-	To <<def_merge,merge>> more than two <<def_branch,branches>>. Also denotes an
-	intelligent predator.
+	To <<def_merge,merge>> more than two <<def_branch,branches>>.
 
 [[def_origin]]origin::
 	The default upstream <<def_repository,repository>>. Most projects have
@@ -468,9 +452,7 @@ should not be combined with other pathspec.
 	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
+	the `commit` command. A tag is most typically used to mark a particular
 	point in the commit ancestry <<def_chain,chain>>.
 
 [[def_tag_object]]tag object::
@@ -494,7 +476,7 @@ should not be combined with other pathspec.
 [[def_tree_object]]tree object::
 	An <<def_object,object>> containing a list of file names and modes along
 	with refs to the associated blob and/or tree objects. A
-	<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
+	<<def_tree,tree>> is equivalent to a directory.
 
 [[def_tree-ish]]tree-ish::
 	A <<def_ref,ref>> pointing to either a <<def_commit_object,commit
-- 
1.8.1.msysgit.1


---
Thomas

Re: [PATCH 1/3] Remove outdated/missleading/irrelevant entries from glossary-content.txt

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> -[[def_directory]]directory::
> -	The list you get with "ls" :-)
> -

The text indeed has a room for improvement, but it probably makes
sense to have an entry for `directory` here, as folks who are used
to say "Folders" may not know what it is.

> -[[def_evil_merge]]evil merge::
> -	An evil merge is a <<def_merge,merge>> that introduces changes that
> -	do not appear in any <<def_parent,parent>>.

Which one of outdated, misleading or irrelevant category does this
fall into?  It certainly is not outdated (diff --cc/-c is often a
way to view evil merges), the text defines what an evil merge is
precisely and I do not think it is misleading.  Is it irrelevant?

> @@ -468,9 +452,7 @@ should not be combined with other pathspec.
>  	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
> +	the `commit` command. A tag is most typically used to mark a particular
>  	point in the commit ancestry <<def_chain,chain>>.

Even though I personally am slightly in favor of removal, I suspect
that is primarily because I already know what Git tag is, and it is
different from the type tag in the Lisp-speak.

It's similar in spirit why I would prefer to keep `directory` to
help people who speak of "Folders".

Other changes in this patch look OK to me.

[PATCH 2/3] Improve description of SHA1 related topics in glossary-content.txt

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/glossary-content.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index ab02238..05bfebc 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -146,7 +146,7 @@ to point at the new commit.
 	created. Configured via the `.git/info/grafts` file.
 
 [[def_hash]]hash::
-	In Git's context, synonym to <<def_object_name,object name>>.
+	In Git's context, synonym for <<def_object_name,object name>>.
 
 [[def_head]]head::
 	A <<def_ref,named reference>> to the <<def_commit,commit>> at the tip of a
@@ -230,10 +230,9 @@ This commit is referred to as a "merge commit", or sometimes just a
 	Synonym for <<def_object_name,object name>>.
 
 [[def_object_name]]object name::
-	The unique identifier of an <<def_object,object>>. The <<def_hash,hash>>
-	of the object's contents using the Secure Hash Algorithm
-	1 and usually represented by the 40 character hexadecimal encoding of
-	the <<def_hash,hash>> of the object.
+	The unique identifier of an <<def_object,object>>: The <<def_SHA1,SHA1>> hash
+	of the object's contents. The object name is usually represented by the 
+	40 character hexadecimal encoding of the hash value.
 
 [[def_object_type]]object type::
 	One of the identifiers "<<def_commit_object,commit>>",
@@ -426,7 +425,8 @@ should not be combined with other pathspec.
 	Source code management (tool).
 
 [[def_SHA1]]SHA1::
-	Synonym for <<def_object_name,object name>>.
+	"Secure Hash Algorithm 1"; a cryptographic hash function. 
+	In the context of Git used as a synonym for <<def_object_name,object name>>.
 
 [[def_shallow_repository]]shallow repository::
 	A shallow <<def_repository,repository>> has an incomplete
-- 
1.8.1.msysgit.1


---
Thomas

Re: [PATCH 2/3] Improve description of SHA1 related topics in glossary-content.txt

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  Documentation/glossary-content.txt | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index ab02238..05bfebc 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -146,7 +146,7 @@ to point at the new commit.
>  	created. Configured via the `.git/info/grafts` file.
>  
>  [[def_hash]]hash::
> -	In Git's context, synonym to <<def_object_name,object name>>.
> +	In Git's context, synonym for <<def_object_name,object name>>.

OK.

>  [[def_object_name]]object name::
> -	The unique identifier of an <<def_object,object>>. The <<def_hash,hash>>
> -	of the object's contents using the Secure Hash Algorithm
> -	1 and usually represented by the 40 character hexadecimal encoding of
> -	the <<def_hash,hash>> of the object.
> +	The unique identifier of an <<def_object,object>>: The <<def_SHA1,SHA1>> hash
> +	of the object's contents. The object name is usually represented by the 
> +	40 character hexadecimal encoding of the hash value.

I am torn on this one.  When you have a file A on the filesystem,
the object name of the blob that records the contents of that file
is *not* the same as output from "sha1sum A".

I doubt we should spell out _how_ it is computed.  In the glossary,
it is better to say what it is and what it is used for; the tutorial
and Documentation/technical/ give better details that the readers
who refer to the glossary do not need.

	The unique identifier of an <<def_object,object>>.  The
	object name is usually represented by a 40 character
	hexadecimal string.  Also colloquially called
	<<def_SHA1,SHA-1>>.

might be sufficient.

> @@ -426,7 +425,8 @@ should not be combined with other pathspec.
>  	Source code management (tool).
>  
>  [[def_SHA1]]SHA1::
> -	Synonym for <<def_object_name,object name>>.
> +	"Secure Hash Algorithm 1"; a cryptographic hash function. 
> +	In the context of Git used as a synonym for <<def_object_name,object name>>.

We should spell it as "SHA-1" with a dash.

[PATCH 3/3] Remove definition of refspec and pathspec from glossary-content.txt

[Thomas Ackermann]

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
---
 Documentation/glossary-content.txt | 65 ++------------------------------------
 1 file changed, 3 insertions(+), 62 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 05bfebc..1c9c522 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -261,59 +261,7 @@ This commit is referred to as a "merge commit", or sometimes just a
 	pack.
 
 [[def_pathspec]]pathspec::
-       Pattern used to specify paths.
-+
-Pathspecs are used on the command line of "git ls-files", "git
-ls-tree", "git add", "git grep", "git diff", "git checkout",
-and many other commands to
-limit the scope of operations to some subset of the tree or
-worktree.  See the documentation of each command for whether
-paths are relative to the current directory or toplevel.  The
-pathspec syntax is as follows:
-
-* any path matches itself
-* the pathspec up to the last slash represents a
-  directory prefix.  The scope of that pathspec is
-  limited to that subtree.
-* the rest of the pathspec is a pattern for the remainder
-  of the pathname.  Paths relative to the directory
-  prefix will be matched against that pattern using fnmatch(3);
-  in particular, '*' and '?' _can_ match directory separators.
-+
-For example, Documentation/*.jpg will match all .jpg files
-in the Documentation subtree,
-including Documentation/chapter_1/figure_1.jpg.
-
-+
-A pathspec that begins with a colon `:` has special meaning.  In the
-short form, the leading colon `:` is followed by zero or more "magic
-signature" letters (which optionally is terminated by another colon `:`),
-and the remainder is the pattern to match against the path. The optional
-colon that terminates the "magic signature" can be omitted if the pattern
-begins with a character that cannot be a "magic signature" and is not a
-colon.
-+
-In the long form, the leading colon `:` is followed by a open
-parenthesis `(`, a comma-separated list of zero or more "magic words",
-and a close parentheses `)`, and the remainder is the pattern to match
-against the path.
-+
-The "magic signature" consists of an ASCII symbol that is not
-alphanumeric.
-+
---
-top `/`;;
-	The magic word `top` (mnemonic: `/`) makes the pattern match
-	from the root of the working tree, even when you are running
-	the command from inside a subdirectory.
---
-+
-Currently only the slash `/` is recognized as the "magic signature",
-but it is envisioned that we will support more types of magic in later
-versions of Git.
-+
-A pathspec with only a colon means "there is no pathspec". This form
-should not be combined with other pathspec.
+       Pattern used to specify paths in Git commands.
 
 [[def_parent]]parent::
 	A <<def_commit_object,commit object>> contains a (possibly empty) list
@@ -382,15 +330,8 @@ should not be combined with other pathspec.
 [[def_refspec]]refspec::
 	A "refspec" is used by <<def_fetch,fetch>> and
 	<<def_push,push>> to describe the mapping between remote
-	<<def_ref,ref>> and local ref. They are combined with a colon in
-	the format <src>:<dst>, preceded by an optional plus sign, +.
-	For example: `git fetch $URL
-	refs/heads/master:refs/heads/origin` means "grab the master
-	<<def_branch,branch>> <<def_head,head>> from the $URL and store
-	it as my origin branch head". And `git push
-	$URL refs/heads/master:refs/heads/to-upstream` means "publish my
-	master branch head as to-upstream branch at $URL". See also
-	linkgit:git-push[1].
+	<<def_ref,ref>> and local ref. 
+	See linkgit:git-push[1] for details.
 
 [[def_remote_tracking_branch]]remote-tracking branch::
 	A regular Git <<def_branch,branch>> that is used to follow changes from
-- 
1.8.1.msysgit.1


---
Thomas

Re: [PATCH 3/3] Remove definition of refspec and pathspec from glossary-content.txt

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
> ---
>  Documentation/glossary-content.txt | 65 ++------------------------------------
>  1 file changed, 3 insertions(+), 62 deletions(-)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index 05bfebc..1c9c522 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -261,59 +261,7 @@ This commit is referred to as a "merge commit", or sometimes just a
>  	pack.
>  
>  [[def_pathspec]]pathspec::
> +       Pattern used to specify paths in Git commands.

Strictly speaking, it is "used to limit", but in the context of this
document it shouldn't matter either way.

>  
>  [[def_parent]]parent::
>  	A <<def_commit_object,commit object>> contains a (possibly empty) list
> @@ -382,15 +330,8 @@ should not be combined with other pathspec.
>  [[def_refspec]]refspec::
>  	A "refspec" is used by <<def_fetch,fetch>> and
>  	<<def_push,push>> to describe the mapping between remote
> +	<<def_ref,ref>> and local ref. 
> +	See linkgit:git-push[1] for details.

I think we can just drop "See ... for details" from here.  Besides,
why just "push" and not "fetch"?

Aw: Re: [PATCH 3/3] Remove definition of refspec and pathspec from glossary-content.txt

[Thomas Ackermann]

 
> 
> I think we can just drop "See ... for details" from here.  Besides,
> why just "push" and not "fetch"?
> 

I just kept the original reference which only linked to git-push.


---
Thomas

Re: Aw: Re: [PATCH 3/3] Remove definition of refspec and pathspec from glossary-content.txt

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

>  
>> 
>> I think we can just drop "See ... for details" from here.  Besides,
>> why just "push" and not "fetch"?
>> 
>
> I just kept the original reference which only linked to git-push.

That is only because the last example the "See ... for details"
refers to is about 'git push', isn't it?

Aw: Re: Aw: Re: [PATCH 3/3] Remove definition of refspec and pathspec from glossary-content.txt

[Thomas Ackermann]

 
> 
> That is only because the last example the "See ... for details"
> refers to is about 'git push', isn't it?
> 
This is correct but there was no direct link to git-fetch in the first example
and I did not check which combination of man pages gives the complete
definition of refspecs ...


---
Thomas

Re: [PATCH 0/3] Some small fixes to glossary-content.txt

[Junio C Hamano]

Thomas Ackermann <th.acker@arcor.de> writes:

> While proof-reading the user-manual I noticed some issues with glossary-content.txt:
>
> - There is some outdated, misleading or irrelevant information which might only confuse
> new Git users and should therefore be removed.
> - The entries for object, object name and SHA1 lacked a little bit of consistency.
> - The glossary contains partial definitions for refspec and pathspec.

Only on the "partial" bit, and not limited to refspec and pathspec.

I think ideally for any key concepts:

 - The glossary should mention what it is and what it is used for;

 - Individual manual pages should mention how it is constructed and
   how it can be used.  To be complete, it may need to start by
   describing what it is and what it is used for, which may have to
   duplicate what we say in the glossary.

Aw: Re: [PATCH 0/3] Some small fixes to glossary-content.txt

[Thomas Ackermann]

 
> 
> > While proof-reading the user-manual I noticed some issues with
> glossary-content.txt:
> >

I found now mention of my patches in the latest "What's cooking".
Did I miss an action item on my side or got this lost in the noise?


---
Thomas