First stab at glossary

First stab at glossary

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 6614 bytes --]

Hi,

long, long time. Here´s my first stab at the glossary, attached the 
alphabetically sorted, asciidoc marked up txt file (Comments? 
Suggestions? Pizzas?):

object::
	The unit of storage in GIT. It is uniquely identified by
	the SHA1 of its contents. Consequently, an object can not
	be changed.

SHA1::
	A 20-byte sequence (or 41-byte file containing the hex
	representation and a newline). It is calculated from the
	contents of an object by the Secure Hash Algorithm 1.

object database::
	Stores a set of "objects", and an individial object is identified
	by its SHA1 (its ref). The objects are either stored as single
	files, or live inside of packs.

object name::
	Synonym for SHA1.

blob object::
	Untyped object, i.e. the contents of a file.

tree object::
	An object containing a list of blob and/or tree objects.
	(A tree usually corresponds to a directory without
	subdirectories).

tree::
	Either a working tree, or a tree object together with the
	dependent blob and tree objects (i.e. a stored representation
	of a working tree).

cache::
	A collection of files whose contents are stored as objects.
	The cache is a stored version of your working tree. Well, can
	also contain a second, and even a third version of a working
	tree, which are used when merging.

cache entry::
	The information regarding a particular file, stored in the index.
	A cache entry can be unmerged, if a merge was started, but not
	yet finished (i.e. if the cache contains multiple versions of
	that file).

index::
	Contains information about the cache contents, in particular
	timestamps and mode flags ("stat information") for the files
	stored in the cache. An unmerged index is an index which contains
	unmerged cache entries.

working tree::
	The set of files and directories currently being worked on.
	Think "ls -laR"

directory::
	The list you get with "ls" :-)

checkout::
	The action of updating the working tree to a revision which was
	stored in the object database.

revision::
	A particular state of files and directories which was stored in
	the object database. It is referenced by a commit object.

commit::
	The action of storing the current state of the cache in the
	object database. The result is a revision.

commit object::
	An object which contains the information about a particular
	revision, such as parents, committer, author, date and the
	tree object which corresponds to the top directory of the
	stored revision.

changeset::
	BitKeeper/cvsps speak for "commit". Since git does not store
	changes, but states, it really does not make sense to use
	the term "changesets" with git.

ent::
	Favorite synonym to "tree-ish" by some total geeks.

clean::
	A working tree is clean, if it corresponds to the revision
	referenced by the current head.

dirty::
	A working tree is said to be dirty if it contains modifications
	which have not been committed to the current branch.

head::
	The top of a branch. It contains a ref to the corresponding
	commit object.

branch::
	A non-cyclical graph of revisions, i.e. the complete history of
	a particular revision, which does not (yet) have children, which
	is called the branch head. The branch heads are stored in
	$GIT_DIR/refs/heads/.

ref::
	A 40-byte hex representation of a SHA1 pointing to a particular
	object. These are stored in $GIT_DIR/refs/.

head ref::
	A ref pointing to a head. Often, this is abbreviated to "head".
	Head refs are stored in $GIT_DIR/refs/heads/.

tree-ish::
	A ref pointing to either a commit object, a tree object, or a
	tag object pointing to a commit or tree object.

tag object::
	An object containing a ref pointing to another object. It can
	contain a (PGP) signature, in which case it is called "signed
	tag object".

tag::
	A ref pointing to a tag or commit object. In contrast to a head,
	a tag is not changed by a commit. Tags (not tag objects) are
	stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with
	a Lisp tag (which is called object type in git's context).

merge::
	To merge branches means to try to accumulate the changes since a
	common ancestor and apply them to the first branch. An automatic
	merge uses heuristics to accomplish that. Evidently, an automatic
	merge can fail.

resolve::
	The action of fixing up manually what a failed automatic merge
	left behind.

repository::
	A collection of refs together with an object database containing
	all objects, which are reachable from the refs. A repository can
	share an object database with other repositories.

alternate object database::
	Via the alternates mechanism, a repository can inherit part of its
	object database from another object database, which is called
	"alternate".

reachable::
	An object is reachable from a ref/commit/tree/tag, if there is a
	chain leading from the latter to the former.

chain::
	A list of objects, where each object in the list contains a
	reference to its successor (for example, the successor of a commit
	could be one of its parents).

parent::
	A commit object contains a (possibly empty) list of the logical
	predecessor(s) in the line of development, i.e. its parents.

fetch::
	Fetching a branch means to get the branch's head ref from a
	remote repository, to find out which objects are missing from
	the local object database, and to get them, too.

pull::
	Pulling a branch means to fetch it and merge it.

push::
	Pushing a branch means to get the branch's head ref from a remote
	repository, find out if it is an ancestor to the branch's local
	head ref is a direct, and in that case, putting all objects, which
	are reachable from the local head ref, and which are missing from
	the remote repository, into the remote object database, and updating
	the remote head ref. If the remote head is not an ancestor to the
	local head, the push fails.

pack::
	A set of objects which have been compressed into one file (to save
	space or to transmit them efficiently).

pack index::
	Contains offsets into a pack, so the pack can be used instead of
	the unpacked objects.

plumbing::
	Cute name for core git.

porcelain::
	Cute name for programs and program suites depending on core git,
	presenting a high level access to core git. Porcelains expose
	more of a SCM interface than the plumbing.

object type:
	One of the identifiers "commit","tree","tag" and "blob" describing
	the type of an object.

SCM::
	Source code management (tool).

dircache::
	You are *waaaaay* behind.

[-- Attachment #2: Type: TEXT/plain, Size: 9230 bytes --]

GIT Glossary
============
Aug 2005

[[ref_SCM]]SCM::
	Source code management (tool). 

[[ref_SHA1]]SHA1::
	A 20-byte sequence (or 41-byte file containing the hex representation
	and a newline). It is calculated from the contents of an
	<<ref_object,object>> by the Secure Hash Algorithm 1. 

[[ref_alternate_object_database]]alternate object database::
	Via the alternates mechanism, a <<ref_repository,repository>> can
	inherit part of its <<ref_object_database,object database>> from another
	<<ref_object_database,object database>>, which is called "alternate". 

[[ref_blob_object]]blob object::
	Untyped <<ref_object,object>>, i.e. the contents of a file. 

[[ref_branch]]branch::
	A non-cyclical graph of revisions, i.e. the complete history of a
	particular <<ref_revision,revision>>, which does not (yet) have
	children, which is called the <<ref_branch,branch>> <<ref_head,head>>.
	The <<ref_branch,branch>> heads are stored in $GIT_DIR/refs/heads/. 

[[ref_cache]]cache::
	A collection of files whose contents are stored as objects. The
	<<ref_cache,cache>> is a stored version of your
	<<ref_working_tree,working tree>>. Well, can also contain a second, and
	even a third version of a working <<ref_tree,tree>>, which are used when
	merging. 

[[ref_cache_entry]]cache entry::
	The information regarding a particular file, stored in the
	<<ref_index,index>>. A <<ref_cache_entry,cache entry>> can be unmerged,
	if a <<ref_merge,merge>> was started, but not yet finished (i.e. if the
	<<ref_cache,cache>> contains multiple versions of that file). 

[[ref_chain]]chain::
	A list of objects, where each <<ref_object,object>> in the list contains
	a reference to its successor (for example, the successor of a
	<<ref_commit,commit>> could be one of its parents). 

[[ref_changeset]]changeset::
	BitKeeper/cvsps speak for "<<ref_commit,commit>>". Since git does not
	store changes, but states, it really does not make sense to use the term
	"changesets" with git. 

[[ref_checkout]]checkout::
	The action of updating the <<ref_working_tree,working tree>> to a
	<<ref_revision,revision>> which was stored in the
	<<ref_object_database,object database>>. 

[[ref_clean]]clean::
	A <<ref_working_tree,working tree>> is <<ref_clean,clean>>, if it
	corresponds to the <<ref_revision,revision>> referenced by the current
	<<ref_head,head>>. 

[[ref_commit]]commit::
	The action of storing the current state of the <<ref_cache,cache>> in
	the <<ref_object_database,object database>>. The result is a
	<<ref_revision,revision>>. 

[[ref_commit_object]]commit object::
	An <<ref_object,object>> which contains the information about a
	particular <<ref_revision,revision>>, such as parents, committer,
	author, date and the <<ref_tree_object,tree object>> which corresponds
	to the top <<ref_directory,directory>> of the stored
	<<ref_revision,revision>>. 

[[ref_dircache]]dircache::
	You are *waaaaay* behind. 

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

[[ref_dirty]]dirty::
	A <<ref_working_tree,working tree>> is said to be <<ref_dirty,dirty>> if
	it contains modifications which have not been committed to the current
	<<ref_branch,branch>>. 

[[ref_ent]]ent::
	Favorite synonym to "<<ref_tree-ish,tree-ish>>" by some total geeks. 

[[ref_fetch]]fetch::
	Fetching a <<ref_branch,branch>> means to get the
	<<ref_branch,branch>>'s <<ref_head_ref,head ref>> from a remote
	<<ref_repository,repository>>, to find out which objects are missing
	from the local <<ref_object_database,object database>>, and to get them,
	too. 

[[ref_head]]head::
	The top of a <<ref_branch,branch>>. It contains a <<ref_ref,ref>> to the
	corresponding <<ref_commit_object,commit object>>. 

[[ref_head_ref]]head ref::
	A <<ref_ref,ref>> pointing to a <<ref_head,head>>. Often, this is
	abbreviated to "<<ref_head,head>>". Head refs are stored in
	$GIT_DIR/refs/heads/. 

[[ref_index]]index::
	Contains information about the <<ref_cache,cache>> contents, in
	particular timestamps and mode flags ("stat information") for the files
	stored in the <<ref_cache,cache>>. An unmerged <<ref_index,index>> is an
	<<ref_index,index>> which contains unmerged <<ref_cache,cache>> entries.

[[ref_merge]]merge::
	To <<ref_merge,merge>> branches means to try to accumulate the changes
	since a common ancestor and apply them to the first
	<<ref_branch,branch>>. An automatic <<ref_merge,merge>> uses heuristics
	to accomplish that. Evidently, an automatic <<ref_merge,merge>> can
	fail. 

[[ref_object]]object::
	The unit of storage in GIT. It is uniquely identified by the
	<<ref_SHA1,SHA1>> of its contents. Consequently, an
	<<ref_object,object>> can not be changed. 

[[ref_object_database]]object database::
	Stores a set of "objects", and an individial <<ref_object,object>> is
	identified by its <<ref_SHA1,SHA1>> (its <<ref_ref,ref>>). The objects
	are either stored as single files, or live inside of packs. 

[[ref_object_name]]object name::
	Synonym for <<ref_SHA1,SHA1>>. 

[[ref_pack]]pack::
	A set of objects which have been compressed into one file (to save space
	or to transmit them efficiently). 

[[ref_pack_index]]pack index::
	Contains offsets into a <<ref_pack,pack>>, so the <<ref_pack,pack>> can
	be used instead of the unpacked objects. 

[[ref_parent]]parent::
	A <<ref_commit_object,commit object>> contains a (possibly empty) list
	of the logical predecessor(s) in the line of development, i.e. its
	parents. 

[[ref_plumbing]]plumbing::
	Cute name for core git. 

[[ref_porcelain]]porcelain::
	Cute name for programs and program suites depending on core git,
	presenting a high level access to core git. Porcelains expose more of a
	<<ref_SCM,SCM>> interface than the <<ref_plumbing,plumbing>>. 

[[ref_pull]]pull::
	Pulling a <<ref_branch,branch>> means to <<ref_fetch,fetch>> it and
	<<ref_merge,merge>> it. 

[[ref_push]]push::
	Pushing a <<ref_branch,branch>> means to get the <<ref_branch,branch>>'s
	<<ref_head_ref,head ref>> from a remote <<ref_repository,repository>>,
	find out if it is an ancestor to the <<ref_branch,branch>>'s local
	<<ref_head_ref,head ref>> is a direct, and in that case, putting all
	objects, which are <<ref_reachable,reachable>> from the local
	<<ref_head_ref,head ref>>, and which are missing from the remote
	<<ref_repository,repository>>, into the remote
	<<ref_object_database,object database>>, and updating the remote
	<<ref_head_ref,head ref>>. If the remote <<ref_head,head>> is not an
	ancestor to the local <<ref_head,head>>, the <<ref_push,push>> fails. 

[[ref_reachable]]reachable::
	An <<ref_object,object>> is <<ref_reachable,reachable>> from a
	<<ref_ref,ref>>/<<ref_commit,commit>>/<<ref_tree,tree>>/<<ref_tag,tag>>,
	if there is a <<ref_chain,chain>> leading from the latter to the former.

[[ref_ref]]ref::
	A 40-byte hex representation of a <<ref_SHA1,SHA1>> pointing to a
	particular <<ref_object,object>>. These are stored in $GIT_DIR/refs/. 

[[ref_repository]]repository::
	A collection of refs together with an <<ref_object_database,object
	database>> containing all objects, which are <<ref_reachable,reachable>>
	from the refs. A <<ref_repository,repository>> can share an
	<<ref_object_database,object database>> with other repositories. 

[[ref_resolve]]resolve::
	The action of fixing up manually what a failed automatic
	<<ref_merge,merge>> left behind. 

[[ref_revision]]revision::
	A particular state of files and directories which was stored in the
	<<ref_object_database,object database>>. It is referenced by a
	<<ref_commit_object,commit object>>. 

[[ref_tag]]tag::
	A <<ref_ref,ref>> pointing to a <<ref_tag,tag>> or
	<<ref_commit_object,commit object>>. In contrast to a <<ref_head,head>>,
	a <<ref_tag,tag>> is not changed by a <<ref_commit,commit>>. Tags (not
	<<ref_tag,tag>> objects) are stored in $GIT_DIR/refs/tags/. A git
	<<ref_tag,tag>> has nothing to do with a Lisp <<ref_tag,tag>> (which is
	called <<ref_object,object>> type in git's context). 

[[ref_tag_object]]tag object::
	An <<ref_object,object>> containing a <<ref_ref,ref>> pointing to
	another <<ref_object,object>>. It can contain a (PGP) signature, in
	which case it is called "signed <<ref_tag_object,tag object>>". 

[[ref_tree]]tree::
	Either a <<ref_working_tree,working tree>>, or a <<ref_tree_object,tree
	object>> together with the dependent blob and <<ref_tree,tree>> objects
	(i.e. a stored representation of a <<ref_working_tree,working tree>>). 

[[ref_tree_object]]tree object::
	An <<ref_object,object>> containing a list of blob and/or
	<<ref_tree,tree>> objects. (A <<ref_tree,tree>> usually corresponds to a
	<<ref_directory,directory>> without subdirectories). 

[[ref_tree-ish]]tree-ish::
	A <<ref_ref,ref>> pointing to either a <<ref_commit_object,commit
	object>>, a <<ref_tree_object,tree object>>, or a <<ref_tag_object,tag
	object>> pointing to a <<ref_commit,commit>> or <<ref_tree_object,tree
	object>>. 

[[ref_working_tree]]working tree::
	The set of files and directories currently being worked on. Think "ls
	-laR" 

Re: First stab at glossary

[Daniel Barkalow]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: TEXT/PLAIN; charset=X-UNKNOWN, Size: 6425 bytes --]

On Wed, 17 Aug 2005, Johannes Schindelin wrote:

> Hi,
>
> long, long time. Here´s my first stab at the glossary, attached the
> alphabetically sorted, asciidoc marked up txt file (Comments?
> Suggestions? Pizzas?):
>
> object::
> 	The unit of storage in GIT. It is uniquely identified by
> 	the SHA1 of its contents. Consequently, an object can not
> 	be changed.
>
> SHA1::
> 	A 20-byte sequence (or 41-byte file containing the hex
> 	representation and a newline). It is calculated from the
> 	contents of an object by the Secure Hash Algorithm 1.

It's also often 40-character string (with whatever termination) in places
like commit objects, tag objects, command-line arguments, listings, and so
forth.

> object database::
> 	Stores a set of "objects", and an individial object is identified
> 	by its SHA1 (its ref). The objects are either stored as single
> 	files, or live inside of packs.
>
> object name::
> 	Synonym for SHA1.

Have we killed the use of the third term "hash" for this? I'd say that
"object name" is the standard term, and "SHA1" is a nickname, if only
because "object name" is more descriptive of the particular use of the
term.

> blob object::
> 	Untyped object, i.e. the contents of a file.

This "i.e." should be "e.g.", since symlink targets are also stored as
blobs, and any other bulk data stored by itself would be. (IIRC, Junio has
a tagged blob to hold his public key, for example)

> tree object::
> 	An object containing a list of blob and/or tree objects.
> 	(A tree usually corresponds to a directory without
> 	subdirectories).
>
> tree::
> 	Either a working tree, or a tree object together with the
> 	dependent blob and tree objects (i.e. a stored representation
> 	of a working tree).
>
> cache::
> 	A collection of files whose contents are stored as objects.
> 	The cache is a stored version of your working tree. Well, can
> 	also contain a second, and even a third version of a working
> 	tree, which are used when merging.
>
> cache entry::
> 	The information regarding a particular file, stored in the index.
> 	A cache entry can be unmerged, if a merge was started, but not
> 	yet finished (i.e. if the cache contains multiple versions of
> 	that file).
>
> index::
> 	Contains information about the cache contents, in particular
> 	timestamps and mode flags ("stat information") for the files
> 	stored in the cache. An unmerged index is an index which contains
> 	unmerged cache entries.

I think we might want to entirely kill the "cache" term, and talk only
about the "index" and "index entries". Of course, a bunch of the code will
have to be renamed to make this completely successful, but we could change
the glossary and documentation, and mention "cache" and "cache entry" as
old names for "index" and "index entry" respectively.

> working tree::
> 	The set of files and directories currently being worked on.
> 	Think "ls -laR"

This is where the data is actually in the filesystem, and you can edit and
compile it (as opposed to a tree object or the index, which semantically
have the same contents, but aren't presented in the filesystem that way).

> directory::
> 	The list you get with "ls" :-)
>
> checkout::
> 	The action of updating the working tree to a revision which was
> 	stored in the object database.

Move after "revision"?

> revision::
> 	A particular state of files and directories which was stored in
> 	the object database. It is referenced by a commit object.
>
> commit::
> 	The action of storing the current state of the cache in the
> 	object database. The result is a revision.
>
> commit object::
> 	An object which contains the information about a particular
> 	revision, such as parents, committer, author, date and the
> 	tree object which corresponds to the top directory of the
> 	stored revision.

Move "parent" around here.

> changeset::
> 	BitKeeper/cvsps speak for "commit". Since git does not store
> 	changes, but states, it really does not make sense to use
> 	the term "changesets" with git.
>
> ent::
> 	Favorite synonym to "tree-ish" by some total geeks.

Move after "tree-ish".

> head::
> 	The top of a branch. It contains a ref to the corresponding
> 	commit object.
>
> branch::
> 	A non-cyclical graph of revisions, i.e. the complete history of
> 	a particular revision, which does not (yet) have children, which
> 	is called the branch head. The branch heads are stored in
> 	$GIT_DIR/refs/heads/.

A branch head might have children, if they're in another branch. (E.g., I
pull mainline, make a new branch based on it, and commit a change; the
head of mainline is still a branch head, even though it's the parent of my
new commit, because my new commit isn't in mainline.)

> ref::
> 	A 40-byte hex representation of a SHA1 pointing to a particular
> 	object. These are stored in $GIT_DIR/refs/.
>
> head ref::
> 	A ref pointing to a head. Often, this is abbreviated to "head".
> 	Head refs are stored in $GIT_DIR/refs/heads/.
>
> tree-ish::
> 	A ref pointing to either a commit object, a tree object, or a
> 	tag object pointing to a commit or tree object.
>
> tag object::
> 	An object containing a ref pointing to another object. It can
> 	contain a (PGP) signature, in which case it is called "signed
> 	tag object".
>
> tag::
> 	A ref pointing to a tag or commit object. In contrast to a head,
> 	a tag is not changed by a commit. Tags (not tag objects) are
> 	stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with
> 	a Lisp tag (which is called object type in git's context).

As above, only the head for the branch being committed to is changed by a
commit. A tag, not being the head of a branch, is therefore never changed
by a commit.

> merge::
> 	To merge branches means to try to accumulate the changes since a
> 	common ancestor and apply them to the first branch. An automatic
> 	merge uses heuristics to accomplish that. Evidently, an automatic
> 	merge can fail.
>
> resolve::
> 	The action of fixing up manually what a failed automatic merge
> 	left behind.

"Resolve" is also used for the automatic case (e.g., in
"git-resolve-script", which goes from having two commits and a message to
having a new commit). I'm not sure what the distinction is supposed to be.

	-Daniel
*This .sig left intentionally blank*

Re: First stab at glossary

[Johannes Schindelin]

Hi,

On Wed, 17 Aug 2005, Daniel Barkalow wrote:

> On Wed, 17 Aug 2005, Johannes Schindelin wrote:
> 
> > SHA1::
> > 	A 20-byte sequence (or 41-byte file containing the hex
> > 	representation and a newline). It is calculated from the
> > 	contents of an object by the Secure Hash Algorithm 1.
> 
> It's also often 40-character string (with whatever termination) in places
> like commit objects, tag objects, command-line arguments, listings, and so
> forth.

Okay.

> > object name::
> > 	Synonym for SHA1.
> 
> Have we killed the use of the third term "hash" for this? I'd say that
> "object name" is the standard term, and "SHA1" is a nickname, if only
> because "object name" is more descriptive of the particular use of the
> term.

Okay for "hash". What is the consensus on "object name" being more 
standard than "SHA1"?

> > blob object::
> > 	Untyped object, i.e. the contents of a file.
> 
> This "i.e." should be "e.g.", since symlink targets are also stored as
> blobs, and any other bulk data stored by itself would be. (IIRC, Junio has
> a tagged blob to hold his public key, for example)

Agree.

> I think we might want to entirely kill the "cache" term, and talk only
> about the "index" and "index entries". Of course, a bunch of the code will
> have to be renamed to make this completely successful, but we could change
> the glossary and documentation, and mention "cache" and "cache entry" as
> old names for "index" and "index entry" respectively.

For me, "index" is just the file named "index" (holding stat data and a 
ref for each cache entry). That is why I say an "index" contains "cache 
entries", not "index entries" (wee, that sounds wrong :-).

> > working tree::
> > 	The set of files and directories currently being worked on.
> > 	Think "ls -laR"
> 
> This is where the data is actually in the filesystem, and you can edit and
> compile it (as opposed to a tree object or the index, which semantically
> have the same contents, but aren't presented in the filesystem that way).

Maybe I was too cautious. Linus very new idea was to think of the lowest 
level of an SCM as a file system. But I did not want to mention that. 
Thinking of it again, maybe I should.

> > checkout::
>
> Move after "revision"?

Ultimately, the glossary terms will be sorted alphabetically. If you look 
at the file attached to my original mail, this is already sorted and 
marked up using asciidoc. However, I wanted you and the list to understand 
how I grouped terms. The asciidoc'ed file is generated by a perl script.

> Move "parent" around here.

See above.

> Move after "tree-ish".

Ditto.

> > branch::
> > 	A non-cyclical graph of revisions, i.e. the complete history of
> > 	a particular revision, which does not (yet) have children, which
> > 	is called the branch head. The branch heads are stored in
> > 	$GIT_DIR/refs/heads/.
> 
> A branch head might have children, if they're in another branch. (E.g., I
> pull mainline, make a new branch based on it, and commit a change; the
> head of mainline is still a branch head, even though it's the parent of my
> new commit, because my new commit isn't in mainline.)

Well noted! I'll just delete that part.

> > tag::
> > 	A ref pointing to a tag or commit object. In contrast to a head,
> > 	a tag is not changed by a commit. Tags (not tag objects) are
> > 	stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with
> > 	a Lisp tag (which is called object type in git's context).
> 
> As above, only the head for the branch being committed to is changed by a
> commit. A tag, not being the head of a branch, is therefore never changed
> by a commit.

I tried to say that.

> > resolve::
> > 	The action of fixing up manually what a failed automatic merge
> > 	left behind.
> 
> "Resolve" is also used for the automatic case (e.g., in
> "git-resolve-script", which goes from having two commits and a message to
> having a new commit). I'm not sure what the distinction is supposed to be.

I did not like that naming anyway. In reality, git-resolve-script does not 
resolve anything, but it merges two revisions, possibly leaving something 
to resolve.

Ciao,
Dscho

Re: First stab at glossary

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Okay for "hash". What is the consensus on "object name" being more 
> standard than "SHA1"?

The tutorial uses the term "object name", so does README
(implicitly, by saying "All objects are named by their content,
which is approximated by the SHA1 hash of the object itself").
I think it is pretty safe to assume the list agrees with this
term.

> For me, "index" is just the file named "index" (holding stat data and a 
> ref for each cache entry). That is why I say an "index" contains "cache 
> entries", not "index entries" (wee, that sounds wrong :-).

I think Linus already commented on using "index file" and "index
entries" as the canonical terms.  It would be a good idea to
mention "cache" as a historical synonym in the documentation, so
that we do not have to rename the symbols in the code.

> Ultimately, the glossary terms will be sorted alphabetically. If you look 
> at the file attached to my original mail, this is already sorted and 
> marked up using asciidoc. However, I wanted you and the list to understand 
> how I grouped terms. The asciidoc'ed file is generated by a perl script.

Then we should put the text version under Documentation, along
with that script and a Makefile entry to do asciidoc and another
to go to html.  No rush for the script and Makefile entries, but
it would make things easier to manage if we put the text version
in the tree soonish.  I've pushed out the one from your original
"First stab" message.

>> > branch::
>> > 	A non-cyclical graph of revisions, i.e. the complete history of
>> > 	a particular revision, which does not (yet) have children, which
>> > 	is called the branch head. The branch heads are stored in
>> > 	$GIT_DIR/refs/heads/.

I wonder if there is a math term for a non-cyclical graph that
has a single "greater than anything else in the graph" node (but
not necessarily a single but possibly more "lesser than anything
else in the graph" nodes)?

>> > tag::
>> > 	A ref pointing to a tag or commit object. In contrast to a head,
>> > 	a tag is not changed by a commit. Tags (not tag objects) are
>> > 	stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with
>> > 	a Lisp tag (which is called object type in git's context).

I think this is good already, but maybe mention why you would
use a tag in a sentence?  "Most typically used to mark a
particular point in the commit ancestry chain," or something.

>> > resolve::
>> > 	The action of fixing up manually what a failed automatic merge
>> > 	left behind.
>> 
>> "Resolve" is also used for the automatic case (e.g., in
>> "git-resolve-script", which goes from having two commits and a message to
>> having a new commit). I'm not sure what the distinction is supposed to be.
>
> I did not like that naming anyway. In reality, git-resolve-script does not 
> resolve anything, but it merges two revisions, possibly leaving something 
> to resolve.

I am sure this would break people's script, but I am not against
renaming git-resolve-script to say git-merge-script.

Anyway, thanks for doing this less-fun and not-so-glorious job.

Re: First stab at glossary

[Johannes Schindelin]

Hi,

On Wed, 17 Aug 2005, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > Okay for "hash". What is the consensus on "object name" being more 
> > standard than "SHA1"?
> 
> The tutorial uses the term "object name", so does README
> (implicitly, by saying "All objects are named by their content,
> which is approximated by the SHA1 hash of the object itself").
> I think it is pretty safe to assume the list agrees with this
> term.

Okay, I'll give in, then.

> 
> > For me, "index" is just the file named "index" (holding stat data and a 
> > ref for each cache entry). That is why I say an "index" contains "cache 
> > entries", not "index entries" (wee, that sounds wrong :-).
> 
> I think Linus already commented on using "index file" and "index
> entries" as the canonical terms.  It would be a good idea to
> mention "cache" as a historical synonym in the documentation, so
> that we do not have to rename the symbols in the code.
> 

If the king penguin speaketh, the little blue penguin followeth.

> > Ultimately, the glossary terms will be sorted alphabetically. If you look 
> > at the file attached to my original mail, this is already sorted and 
> > marked up using asciidoc. However, I wanted you and the list to understand 
> > how I grouped terms. The asciidoc'ed file is generated by a perl script.
> 
> Then we should put the text version under Documentation, along
> with that script and a Makefile entry to do asciidoc and another
> to go to html.  No rush for the script and Makefile entries, but
> it would make things easier to manage if we put the text version
> in the tree soonish.  I've pushed out the one from your original
> "First stab" message.

Okay. Then I follow the advice of the large and angry Saucer Crunching 
Monster, and shuffle the entries into a more logical order.

> >> > branch::
> >> > 	A non-cyclical graph of revisions, i.e. the complete history of
> >> > 	a particular revision, which does not (yet) have children, which
> >> > 	is called the branch head. The branch heads are stored in
> >> > 	$GIT_DIR/refs/heads/.
> 
> I wonder if there is a math term for a non-cyclical graph that
> has a single "greater than anything else in the graph" node (but
> not necessarily a single but possibly more "lesser than anything
> else in the graph" nodes)?

Yes, there is. Although git itself is an example that there are two 
"greater than almost anything else in the graph" nodes.

Also, let's not be overzealous with our math degrees, okay? :-)

> >> > tag::
> >> > 	A ref pointing to a tag or commit object. In contrast to a head,
> >> > 	a tag is not changed by a commit. Tags (not tag objects) are
> >> > 	stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with
> >> > 	a Lisp tag (which is called object type in git's context).
> 
> I think this is good already, but maybe mention why you would
> use a tag in a sentence?  "Most typically used to mark a
> particular point in the commit ancestry chain," or something.

Done.

> >> > resolve::
> >> > 	The action of fixing up manually what a failed automatic merge
> >> > 	left behind.
> >> 
> >> "Resolve" is also used for the automatic case (e.g., in
> >> "git-resolve-script", which goes from having two commits and a message to
> >> having a new commit). I'm not sure what the distinction is supposed to be.
> >
> > I did not like that naming anyway. In reality, git-resolve-script does not 
> > resolve anything, but it merges two revisions, possibly leaving something 
> > to resolve.
> 
> I am sure this would break people's script, but I am not against
> renaming git-resolve-script to say git-merge-script.

I do not mind changing the description if the consensus is to keep 
git-resolve-script.

> Anyway, thanks for doing this less-fun and not-so-glorious job.

The little blue penguin says: Thanks for all the fish!

Re: First stab at glossary

[Daniel Barkalow]

On Wed, 17 Aug 2005, Johannes Schindelin wrote:

> Hi,
>
> On Wed, 17 Aug 2005, Daniel Barkalow wrote:
>
> > On Wed, 17 Aug 2005, Johannes Schindelin wrote:
> >
> > > object name::
> > > 	Synonym for SHA1.
> >
> > Have we killed the use of the third term "hash" for this? I'd say that
> > "object name" is the standard term, and "SHA1" is a nickname, if only
> > because "object name" is more descriptive of the particular use of the
> > term.
>
> Okay for "hash".

I think we only need at most two names for this, so this is more a matter
of fixing old usage than documenting it.

> > I think we might want to entirely kill the "cache" term, and talk only
> > about the "index" and "index entries". Of course, a bunch of the code will
> > have to be renamed to make this completely successful, but we could change
> > the glossary and documentation, and mention "cache" and "cache entry" as
> > old names for "index" and "index entry" respectively.
>
> For me, "index" is just the file named "index" (holding stat data and a
> ref for each cache entry). That is why I say an "index" contains "cache
> entries", not "index entries" (wee, that sounds wrong :-).

Well, it often contains information not present anywhere else (the status
of a merge; the set of files being committed, added, or removed), so it
isn't really a cache at all.

> > > working tree::
> > > 	The set of files and directories currently being worked on.
> > > 	Think "ls -laR"
> >
> > This is where the data is actually in the filesystem, and you can edit and
> > compile it (as opposed to a tree object or the index, which semantically
> > have the same contents, but aren't presented in the filesystem that way).
>
> Maybe I was too cautious. Linus very new idea was to think of the lowest
> level of an SCM as a file system. But I did not want to mention that.
> Thinking of it again, maybe I should.

You probably don't need to mention that tree objects and index files can
be thought of as filesystems, but you should specify that the working tree
really is in the Unix filesystem, in case people have heard of the idea.

It should be clear to say 'You can "cd" there and "ls" to list your
files.', rather than 'Think "ls -laR"' which makes my think of the output,
which is like the output from git-ls-files.

> > > checkout::
> >
> > Move after "revision"?
>
> Ultimately, the glossary terms will be sorted alphabetically. If you look
> at the file attached to my original mail, this is already sorted and
> marked up using asciidoc. However, I wanted you and the list to understand
> how I grouped terms. The asciidoc'ed file is generated by a perl script.

Ah, okay.

> > > resolve::
> > > 	The action of fixing up manually what a failed automatic merge
> > > 	left behind.
> >
> > "Resolve" is also used for the automatic case (e.g., in
> > "git-resolve-script", which goes from having two commits and a message to
> > having a new commit). I'm not sure what the distinction is supposed to be.
>
> I did not like that naming anyway. In reality, git-resolve-script does not
> resolve anything, but it merges two revisions, possibly leaving something
> to resolve.

Right; I think we should change the name of the script.

	-Daniel
*This .sig left intentionally blank*

Re: First stab at glossary

[Johannes Schindelin]

Hi,

On Wed, 17 Aug 2005, Daniel Barkalow wrote:

> On Wed, 17 Aug 2005, Johannes Schindelin wrote:
> 
> > On Wed, 17 Aug 2005, Daniel Barkalow wrote:
> > > [...]
> > Okay for "hash".
> 
> I think we only need at most two names for this, so this is more a matter
> of fixing old usage than documenting it.

It's short enough to keep it in the glossary _and_ fix the old 
documentation.

> > [blabla] index [blable] cache [bliblo]
>
> Well, it often contains information not present anywhere else (the status
> of a merge; the set of files being committed, added, or removed), so it
> isn't really a cache at all.

Okay, okay. I stand corrected.

> > Maybe I was too cautious. Linus very new idea was to think of the lowest
> > level of an SCM as a file system. But I did not want to mention that.
> > Thinking of it again, maybe I should.
> 
> You probably don't need to mention that tree objects and index files can
> be thought of as filesystems, but you should specify that the working tree
> really is in the Unix filesystem, in case people have heard of the idea.
> 
> It should be clear to say 'You can "cd" there and "ls" to list your
> files.', rather than 'Think "ls -laR"' which makes my think of the output,
> which is like the output from git-ls-files.

How about this:

working tree::
        The set of files and directories currently being worked on,
        i.e. you can work in your working tree without using git at all.


> > > > checkout::
> > >
> > > Move after "revision"?
> >
> > Ultimately, the glossary terms will be sorted alphabetically. If you look
> > at the file attached to my original mail, this is already sorted and
> > marked up using asciidoc. However, I wanted you and the list to understand
> > how I grouped terms. The asciidoc'ed file is generated by a perl script.
> 
> Ah, okay.

Sorry, I attributed these "moving suggestions" to the large and angry SCM, 
while those were your comments. Since Junio decided to keep the "topic 
ordered" form in his repository, I moved them around according to your 
mail.

> > > > resolve::
> > > > 	The action of fixing up manually what a failed automatic merge
> > > > 	left behind.
> > >
> > > "Resolve" is also used for the automatic case (e.g., in
> > > "git-resolve-script", which goes from having two commits and a message to
> > > having a new commit). I'm not sure what the distinction is supposed to be.
> >
> > I did not like that naming anyway. In reality, git-resolve-script does not
> > resolve anything, but it merges two revisions, possibly leaving something
> > to resolve.
> 
> Right; I think we should change the name of the script.

How many users are there? Probably many call git-pull-script anyway, 
right?

Ciao,
Dscho

Tool renames? was Re: First stab at glossary

[Tim Ottinger]

So when this gets all settled, will we see a lot of tool renaming? 

While it would cause me and my team some personal effort (we have
a special-purpose porcelain), it would be welcome to have a lexicon
that is sane and consistent, and in tune with all the documentation.

Others may feel differently, I understand.

-- 
                             ><>
... either 'way ahead of the game, or 'way out in left field.

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Tim Ottinger <tottinge@progeny.com> writes:

> So when this gets all settled, will we see a lot of tool renaming? 

I personally do not see it coming.  Any particular one you have
in mind?

Re: Tool renames? was Re: First stab at glossary

[Tim Ottinger]

Junio C Hamano wrote:

>Tim Ottinger <tottinge@progeny.com> writes:
>
>  
>
>>So when this gets all settled, will we see a lot of tool renaming? 
>>    
>>
>
>I personally do not see it coming.  Any particular one you have
>in mind?
>
>  
>
git-update-cache for instance?
I am not sure which 'cache' commands need to be 'index' now.


-- 
                             ><>
... either 'way ahead of the game, or 'way out in left field.

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Tim Ottinger <tottinge@progeny.com> writes:

> git-update-cache for instance?
> I am not sure which 'cache' commands need to be 'index' now.

Logically you are right, but I suspect that may not fly well in
practice.  Too many of us have already got our fingers wired to
type cache, and the glossary is there to describe both cache and
index.

 

Re: Tool renames? was Re: First stab at glossary

[Horst von Brand]

Junio C Hamano <junkio@cox.net> wrote:
> Tim Ottinger <tottinge@progeny.com> writes:
> > git-update-cache for instance?
> > I am not sure which 'cache' commands need to be 'index' now.

> Logically you are right, but I suspect that may not fly well in
> practice.  Too many of us have already got our fingers wired to
> type cache, and the glossary is there to describe both cache and
> index.

I'd vote for cleaning it up /now/. Sure, it will hurt, but if you let time
go by and do it later, it will hurt much more.

Pre-1.0 is the last chance, AFAICS.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: Tool renames? was Re: First stab at glossary

[Daniel Barkalow]

On Thu, 1 Sep 2005, Junio C Hamano wrote:

> Tim Ottinger <tottinge@progeny.com> writes:
> 
> > git-update-cache for instance?
> > I am not sure which 'cache' commands need to be 'index' now.
> 
> Logically you are right, but I suspect that may not fly well in
> practice.  Too many of us have already got our fingers wired to
> type cache, and the glossary is there to describe both cache and
> index.

My vote's for changing the official names, but keeping symlinks for the 
old names. As far as I know, there aren't any actual conflicts, and we 
might as well have new users pick up the logical names. I particularly 
think "git merge" would be really good to have.

	-Daniel
*This .sig left intentionally blank*

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Daniel Barkalow <barkalow@iabervon.org> writes:

> On Thu, 1 Sep 2005, Junio C Hamano wrote:
>
>> Tim Ottinger <tottinge@progeny.com> writes:
>> 
>> > git-update-cache for instance?
>> 
>> Logically you are right, but I suspect that may not fly well in
>> practice.  Too many of us have already got our fingers wired to
>> type cache, and the glossary is there to describe both cache and
>> index.
>
> My vote's for changing the official names, but keeping symlinks for the 
> old names. As far as I know, there aren't any actual conflicts, and we 
> might as well have new users pick up the logical names. I particularly 
> think "git merge" would be really good to have.

OK.  As Horst also says, we should do this before 1.0.

0.99.6::
	This hopefully will be done on Sep 7th.  Tool renames
	will not happen in this release, but the set of cleaned
	up names will be discussed on the list during this
	timeperiod.  I'll draw up a strawman tonight unless
	somebody else does it first.

0.99.7::
	We install symbolic links for the old names.  For the
	documentation, we do not bother --- just install under
	new names.  Also remove support for ancient environment
	variable names from gitenv().  Aim for Sep 17th.

0.99.8::
	Aim for Oct 1st; we do not install symbolic links
	anymore and supply "clean-old-install" target in the
	Makefile that removes symlinks installed by 0.99.7 from
	DESTDIR.  This target is not run automatically from other
	usual make targets; it is just there for your
	convenience.

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

I said:

> 	I'll draw up a strawman tonight unless somebody else
> 	does it first.

1. Say 'index' when you are tempted to say 'cache'.

        git-checkout-cache      git-checkout-index
        git-convert-cache       git-convert-index
        git-diff-cache          git-diff-index
        git-fsck-cache          git-fsck-index
        git-merge-cache         git-merge-index
        git-update-cache        git-update-index

2. The act of combining two or more heads is called 'merging';
   fetching immediately followed by merging is called 'pulling'.

        git-resolve-script      git-merge-script

   The commit walkers are called *-pull, but this is probably
   confusing.  They are not pulling.

        git-http-pull           git-http-walk
        git-local-pull          git-local-walk
        git-ssh-pull            git-ssh-walk

3. Non-binaries are called '*-scripts'.

   In earlier discussions some people seem to like the
   distinction between *-script and others; I did not
   particularly like it, but I am throwing this in for
   discussion.

        git-applymbox           git-applymbox-script
        git-applypatch          git-applypatch-script
        git-cherry              git-cherry-script
        git-shortlog            git-shortlog-script
        git-whatchanged         git-whatchanged-script

4. To be removed shortly.

        git-clone-dumb-http     should be folded into git-clone-script

Re: Tool renames? was Re: First stab at glossary

[Daniel Barkalow]

On Fri, 2 Sep 2005, Junio C Hamano wrote:

> I said:
> 
> > 	I'll draw up a strawman tonight unless somebody else
> > 	does it first.
> 
> 1. Say 'index' when you are tempted to say 'cache'.
> 
>         git-checkout-cache      git-checkout-index
>         git-convert-cache       git-convert-index
>         git-diff-cache          git-diff-index
>         git-fsck-cache          git-fsck-index
>         git-merge-cache         git-merge-index
>         git-update-cache        git-update-index

Agreed, except that git-convert-cache and git-fsck-cache actually have 
nothing to do this the index by any name, and should probably be 
git-convert-objects and git-fsck-objects.

> 2. The act of combining two or more heads is called 'merging';
>    fetching immediately followed by merging is called 'pulling'.
> 
>         git-resolve-script      git-merge-script
> 
>    The commit walkers are called *-pull, but this is probably
>    confusing.  They are not pulling.
> 
>         git-http-pull           git-http-walk
>         git-local-pull          git-local-walk
>         git-ssh-pull            git-ssh-walk

I think "fetch" is more applicable to what they do.

> 3. Non-binaries are called '*-scripts'.
> 
>    In earlier discussions some people seem to like the
>    distinction between *-script and others; I did not
>    particularly like it, but I am throwing this in for
>    discussion.
> 
>         git-applymbox           git-applymbox-script
>         git-applypatch          git-applypatch-script
>         git-cherry              git-cherry-script
>         git-shortlog            git-shortlog-script
>         git-whatchanged         git-whatchanged-script

I don't think it matters very much whether something is a script or not; 
on the other hand, it would be good to have "git" list a reasonable set of 
commands to use through the interface, which would exclude, for example, 
git-merge-one-file-script, and include the above commands.

> 4. To be removed shortly.
> 
>         git-clone-dumb-http     should be folded into git-clone-script

Agreed.

	-Daniel
*This .sig left intentionally blank*

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Daniel Barkalow <barkalow@iabervon.org> writes:

> Agreed, except that git-convert-cache and git-fsck-cache actually have 
> nothing to do this the index by any name, and should probably be 
> git-convert-objects and git-fsck-objects.

You are right.

> I think "fetch" is more applicable to what they do.

OK.  then they are git-http-fetch and friends.  How about
git-ssh-push?  The counterpart of fetch-pack/clone-pack is
called upload-pack, so would git-ssh-upload make things more
consistent?  I dunno.

> I don't think it matters very much whether something is a script or not; 
> on the other hand, it would be good to have "git" list a reasonable set of 
> commands to use through the interface, which would exclude, for example, 
> git-merge-one-file-script, and include the above commands.

Are you suggesting to drop -script from git-merge-one-file?
Then git-cherry should perhaps keep its current name.

Re: Tool renames? was Re: First stab at glossary

[Daniel Barkalow]

On Sat, 3 Sep 2005, Junio C Hamano wrote:

> Daniel Barkalow <barkalow@iabervon.org> writes:
> 
> > I think "fetch" is more applicable to what they do.
> 
> OK.  then they are git-http-fetch and friends.  How about
> git-ssh-push?  The counterpart of fetch-pack/clone-pack is
> called upload-pack, so would git-ssh-upload make things more
> consistent?  I dunno.

I like that idea.

> > I don't think it matters very much whether something is a script or not; 
> > on the other hand, it would be good to have "git" list a reasonable set of 
> > commands to use through the interface, which would exclude, for example, 
> > git-merge-one-file-script, and include the above commands.
> 
> Are you suggesting to drop -script from git-merge-one-file?
> Then git-cherry should perhaps keep its current name.

I'd suggest it get a different ending, like .sh or -helper. That way, it's 
distinct both from binaries and from scripts that people run directly.

	-Daniel
*This .sig left intentionally blank*

Re: Tool renames? was Re: First stab at glossary

[Horst von Brand]

Junio C Hamano <junkio@cox.net> wrote:
> I said:
> 
> > 	I'll draw up a strawman tonight unless somebody else
> > 	does it first.

[...]

> 3. Non-binaries are called '*-scripts'.
> 
>    In earlier discussions some people seem to like the
>    distinction between *-script and others; I did not
>    particularly like it, but I am throwing this in for
>    discussion.

I for one think this makes the command name dependent on a non-essential
implementation detail, so -script should go.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Horst von Brand <vonbrand@inf.utfsm.cl> writes:

>> 3. Non-binaries are called '*-scripts'.
>> 
>>    In earlier discussions some people seem to like the
>>    distinction between *-script and others; I did not
>>    particularly like it, but I am throwing this in for
>>    discussion.
>
> I for one think this makes the command name dependent on a non-essential
> implementation detail, so -script should go.

I had the same opinion.  The counter-argument people raised when
this topic came up on the list was that it would help grepping
in the source tree.

I'm tempted to suggest doing something along these lines:

 - Rename things that are implemented in shell from *-script to
   *.sh, and perl to *.perl in the source tree;

 - Install them without .{sh,perl} suffix.

Once this is done, the users nor the 'git' wrapper do not have
to deal with *-script.

Comments?

Re: Tool renames? was Re: First stab at glossary

[Peter Williams]

Junio C Hamano wrote:
> Horst von Brand <vonbrand@inf.utfsm.cl> writes:
> 
> 
>>>3. Non-binaries are called '*-scripts'.
>>>
>>>   In earlier discussions some people seem to like the
>>>   distinction between *-script and others; I did not
>>>   particularly like it, but I am throwing this in for
>>>   discussion.
>>
>>I for one think this makes the command name dependent on a non-essential
>>implementation detail, so -script should go.
> 
> 
> I had the same opinion.  The counter-argument people raised when
> this topic came up on the list was that it would help grepping
> in the source tree.
> 
> I'm tempted to suggest doing something along these lines:
> 
>  - Rename things that are implemented in shell from *-script to
>    *.sh, and perl to *.perl in the source tree;

*.pl is what is usually used for perl scripts.

> 
>  - Install them without .{sh,perl} suffix.
> 
> Once this is done, the users nor the 'git' wrapper do not have
> to deal with *-script.
> 
> Comments?
> 
> 
> -
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html


-- 
Peter Williams                                   pwil3058@bigpond.net.au

"Learning, n. The kind of ignorance distinguishing the studious."
  -- Ambrose Bierce

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Peter Williams <pwil3058@bigpond.net.au> writes:

> *.pl is what is usually used for perl scripts.

My recollection may be faulty, but '*.pl' was meant to be used
for older Perl libraries back in perl4 days, and the standalone
scripts are to be named '*.perl' but many people made the
mistake of naming them '*.pl'.

Re: Tool renames? was Re: First stab at glossary

[Peter Williams]

Junio C Hamano wrote:
> Peter Williams <pwil3058@bigpond.net.au> writes:
> 
> 
>>*.pl is what is usually used for perl scripts.
> 
> 
> My recollection may be faulty, but '*.pl' was meant to be used
> for older Perl libraries back in perl4 days, and the standalone
> scripts are to be named '*.perl' but many people made the
> mistake of naming them '*.pl'.

I'm no expert and was just reporting what I'd observed but that 
observation wasn't thorough enough to notice the distinction that you 
make so forget what I said.  :-)

Peter
-- 
Peter Williams                                   pwil3058@bigpond.net.au

"Learning, n. The kind of ignorance distinguishing the studious."
  -- Ambrose Bierce

Re: Tool renames? was Re: First stab at glossary

[Horst von Brand]

Junio C Hamano <junkio@cox.net> wrote:
> Horst von Brand <vonbrand@inf.utfsm.cl> writes:
> >> 3. Non-binaries are called '*-scripts'.
> >> 
> >>    In earlier discussions some people seem to like the
> >>    distinction between *-script and others; I did not
> >>    particularly like it, but I am throwing this in for
> >>    discussion.

> > I for one think this makes the command name dependent on a non-essential
> > implementation detail, so -script should go.

> I had the same opinion.  The counter-argument people raised when
> this topic came up on the list was that it would help grepping
> in the source tree.

Grepping for what?

It is not /that/ much more expensive to run file(1) over the tree if you
want to know what is a script and what isn't. Furthermore, the "-script"
extension doesn't work for this as of today (see your own message a while
back ;-). Keeping it requires discipline that tools don't help enforcing
today (and the extension use itself is very un-Unix-like), so further
"mistakes" /will/ happen.

In any case, this would be for a very specialized, developer-only,
occasional task. I don't see how that warrants a fractured tool namespace
for /all/ users /all/ the time.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Horst von Brand <vonbrand@inf.utfsm.cl> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> I had the same opinion.  The counter-argument people raised when
>> this topic came up on the list was that it would help grepping
>> in the source tree.
>
> Grepping for what?

I am only a messenger for their argument and, as I said, I did
not particularly buy that argument because I myself do not find
it too disturbing that a grep in my built tree says "Binary file
libgit.a matches", especially I typically run grep in my Emacs
buffer and C-x ` (next-error) does not get confused by such
useless hits.  But I can understand why it matters to people
working in other environments.

> In any case, this would be for a very specialized,
> developer-only, occasional task. I don't see how that warrants
> a fractured tool namespace for /all/ users /all/ the time.

Yes, you convinced the convert again.

Now I have to find a poor unsuspecting volunteer to do the
actual heavylifting after 0.99.6 happens ;-).

Re: Tool renames? was Re: First stab at glossary

[Linus Torvalds]

On Sun, 4 Sep 2005, Horst von Brand wrote:
> > I had the same opinion.  The counter-argument people raised when
> > this topic came up on the list was that it would help grepping
> > in the source tree.
> 
> Grepping for what?

Grepping for strings.

For example, when renaming a binary, the sane way to check that you fixed 
all users right now is

	grep old-binary-name *.c *.h *-scripts

and you catch all users.

In contrast, "grep *" will catch totally uninteresting patterns like 
object files etc.

I personally find that very useful, and I don't see _any_ point to naming 
by what _kind_ of interpreter you use. Why would _anybody_ care whether 
something is written in perl vs shell? There's no reason to name things by 
the interpreter.

		Kubys

Re: Tool renames? was Re: First stab at glossary

[David Kågedal]

Linus Torvalds <torvalds@osdl.org> writes:

> On Sun, 4 Sep 2005, Horst von Brand wrote:
>> > I had the same opinion.  The counter-argument people raised when
>> > this topic came up on the list was that it would help grepping
>> > in the source tree.
>> 
>> Grepping for what?
>
> Grepping for strings.
>
> For example, when renaming a binary, the sane way to check that you fixed 
> all users right now is
>
> 	grep old-binary-name *.c *.h *-scripts
>
> and you catch all users.
>
> In contrast, "grep *" will catch totally uninteresting patterns like 
> object files etc.
>
> I personally find that very useful, and I don't see _any_ point to naming 
> by what _kind_ of interpreter you use. Why would _anybody_ care whether 
> something is written in perl vs shell? There's no reason to name things by 
> the interpreter.

But to the users (like myself), there's no point in naming it by
whether it's a script or a binary.  Since, as a user, I couldn't care
less that git-foobar is a shell script, I don't want to pollute the
command name space with "-script" suffixes.  Calling the command
git-foobar makes much more sense, and allows us to reimplement the
scripts as binaries, or whatever.

So your argument that it makes it easier for git developers to work
with the source doesn't help the user.

The consequence is maybe that the scripts should be called *-script in
the source, but be installed without the suffix?

-- 
David Kågedal

Re: Tool renames? was Re: First stab at glossary

[Linus Torvalds]

On Mon, 5 Sep 2005, David Kågedal wrote:
> 
> But to the users (like myself), there's no point in naming it by
> whether it's a script or a binary. 

So? There's no downside.

To you, as a user, you never see the "-script" ending anyway. You'd never 
type it out, or you're already doing something wrong.

So to users it doesn't matter, and to developers it _does_ matter (and 
calling them ".pl" or ".sh" or something would be _bad_), why not please 
the developers?

> So your argument that it makes it easier for git developers to work
> with the source doesn't help the user.

It doesn't _help_ the user, but since it doesn't hurt him either, why the 
hell would we even _care_ about the user?

		Linus

Re: Tool renames? was Re: First stab at glossary

[David Kågedal]

Linus Torvalds <torvalds@osdl.org> writes:

> On Mon, 5 Sep 2005, David Kågedal wrote:
>> 
>> But to the users (like myself), there's no point in naming it by
>> whether it's a script or a binary. 
>
> So? There's no downside.
>
> To you, as a user, you never see the "-script" ending anyway. You'd never 
> type it out, or you're already doing something wrong.

Then I'm doing something wrong.  And I'm pretty sure others are
too. If I'm not supposed to see the "-script" ending, then don't
install it in my $PATH.

Until someone (possibly myself) writes some zsh completion code to
handle git sub command, I will continue to hit TAB and see all those
names.

Furthermore, the man page for "git clone" is called
"git-clone-script(1)".  And the "-script" suffix appears inside the
documentation in various places.  I see it in howtos and log messages.
And the git-merge-one-file-script script is supposed to be used in a
way where I have to supply the long name.  Etc.

If the "-script" part is supposed to be hidden from me, why do I keep
seeing it everywhere I turn?

> So to users it doesn't matter, and to developers it _does_ matter (and 
> calling them ".pl" or ".sh" or something would be _bad_), why not please 
> the developers?

I'm not suggesting we'd call them ".pl" or ".sh".

-- 
David Kågedal

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> ... and I don't see _any_ point to naming 
> by what _kind_ of interpreter you use. Why would _anybody_ care whether 
> something is written in perl vs shell?

One possibility that comes to mind is to again help developers
who use an editor that is syntax-aware and looks *only* at
filename suffix to figure out which language syntax to use
(Emacs is not one of them -- it knows how to read #! line).

Another is, although we do not currently do it, to make the
Makefile simpler if/when we start to do the interpreter line
munging ("#!/usr/bin/perl -> #!/usr/local/bin/perl") before
install time.

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=iso-2022-jp-2, Size: 1045 bytes --]

David K^[.A^[Negedal <davidk@lysator.liu.se> writes:

> If the "-script" part is supposed to be hidden from me, why do I keep
> seeing it everywhere I turn?
>
>> So to users it doesn't matter, and to developers it _does_ matter (and 
>> calling them ".pl" or ".sh" or something would be _bad_), why not please 
>> the developers?
>
> I'm not suggesting we'd call them ".pl" or ".sh".

Well, I was.  Here is what I had in mind.

1. Introduce SCRIPT_SH and SCRIPT_PERL, and make
   "SCRIPTS = $(SCRIPT_SH) $(SCRIPT_PERL)" in the Makefile.
2. Install git-foo.sh as $(DEST)$(bin)/git-foo
3. Documentation to describe git-foo command is Documentation/git-foo.txt

I was planning to leave gitk source as gitk, not gitk.tcl nor
gitk.wish nor gitk.sh for now, if only to help me merging from
paurus.

Depending on how people would react to the "why would people
care what scripting language is the thing written in" comment by
Linus, I may be persuaded otherwise though, in which case 1. is
not needed, and 2. would lose '.sh', but 3. would not change.
 

Re: Tool renames? was Re: First stab at glossary

[Martin Langhoff]

On 9/6/05, Linus Torvalds <torvalds@osdl.org> wrote:
> Grepping for strings.
> 
> For example, when renaming a binary, the sane way to check that you fixed
> all users right now is
> 
>         grep old-binary-name *.c *.h *-scripts
> 
> and you catch all users.

Grep knows how to ignore binary files. Try:

   grep -I git-commit *

cheers,


martin

Re: Tool renames? was Re: First stab at glossary

[Linus Torvalds]

On Tue, 6 Sep 2005, Martin Langhoff wrote:
> 
> Grep knows how to ignore binary files.

That wasn't the _point_.

The point is, naming things as being "scripts" is useful. Grep is just an 
example. Naming things as being ".pl" or ".sh" is _not_ useful.

So with grep you can use -I, but what about doing things like "em *" when
doing global renames (I use micro-emacs - em - as my editor). Again, "em
*-script" actually works.

The point being that if we have naming rules, make them USEFUL. *-script 
is useful - it works wonderfully well for "git xxx" (which knows to add 
"-script"), and it works wonderfully well for developers. 

		Linus

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> The point is, naming things as being "scripts" is useful. Grep is just an 
> example. Naming things as being ".pl" or ".sh" is _not_ useful.

Sorry, but why not?

Re: Tool renames? was Re: First stab at glossary

[Martin Langhoff]

On 9/6/05, Linus Torvalds <torvalds@osdl.org> wrote:
> That wasn't the _point_.

Agreed - sorry I should have qualified my comment.

I agree with having useful extensions for ease of development. And I
agree with the suggestion of installing them with stripped extensions
-- to extend the abstraction.

OTOH...
> The point is, naming things as being "scripts" is useful. Grep is just an
> example. Naming things as being ".pl" or ".sh" is _not_ useful.

Hrmmm. Not so convinced about that. There are good reasons to
distinguish files with different internal syntax. Perhaps it's your
C-bias but for script maintainers it isn't helpful to deal with
-script prefixes.

If a bash script is rewritten in C, it is a useful and meaningful
change (from a developer perspective) that the file changes name. Both
can live in the tree while the new one matures, running diffs or
pickaxes will show one file created and another removed, instead of a
very meaningless diff. The same applies if it is rewritten in Perl, or
Python.

IOW: Perl programmers are developers too ;-)

cheers,


martin

Re: Tool renames? was Re: First stab at glossary

[Linus Torvalds]

On Tue, 6 Sep 2005, Junio C Hamano wrote:

> Linus Torvalds <torvalds@osdl.org> writes:
> 
> > The point is, naming things as being "scripts" is useful. Grep is just an 
> > example. Naming things as being ".pl" or ".sh" is _not_ useful.
> 
> Sorry, but why not?

What's the upside?

I can point to one downside: "git". That script right now is simple. If 
you rewrite git-cvsimport-script from shell to perl, it looks the same to 
git. 

		Linus

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> What's the upside?
>
> I can point to one downside: "git". That script right now is simple. If 
> you rewrite git-cvsimport-script from shell to perl, it looks the same to 
> git. 

What I've been working on was to:

 * have git-cvsimport.perl in the source

 * install it as $(bindir)/git-cvsimport

 * simplify 'git' (whose source is of course in 'git.sh') to
   only do: 

     cmd="$1"; shift; exec "git-$cmd" ${1+"$@"}

Naturally, the rewrite of git-cvsimport in shell or C would look
the same to git.

One potential downside (for people who consider this a downside)
is that you cannot easily run uninstalled, but you already
cannot run tools/git-applymbox and git-cherry-pick uninstalled
anyway, and I do not think it is such a big deal.

Re: Tool renames? was Re: First stab at glossary

[David Kågedal]

Junio C Hamano <junkio@cox.net> writes:

> Linus Torvalds <torvalds@osdl.org> writes:
>
>> What's the upside?
>>
>> I can point to one downside: "git". That script right now is simple. If 
>> you rewrite git-cvsimport-script from shell to perl, it looks the same to 
>> git. 
>
> What I've been working on was to:
>
>  * have git-cvsimport.perl in the source
>
>  * install it as $(bindir)/git-cvsimport

That was what I suggested too, although I don't really care if it's
called .perl or -script in the source.

By the way, I'm not sure how the 'git' script is supposed to be used.
I know that if there is a git-foo-script file in your path, you can
run it as 'git foo'.  But what about e.g. git-init-db?  You can run
that as 'git init-db' today.  And 'git read-cache' should work too.
And 'git ls-files', and 'git rev-parse', and 'git merge-one-file' and
'git sh-setup-script' in decreasing order of usefulness...

But running 'git' without arguments only list the -script commands as
available.

-- 
David Kågedal

Re: Tool renames? was Re: First stab at glossary

[Tim Ottinger]

Horst von Brand wrote:

>Junio C Hamano <junkio@cox.net> wrote:
>  
>
>>Tim Ottinger <tottinge@progeny.com> writes:
>>    
>>
>>>git-update-cache for instance?
>>>I am not sure which 'cache' commands need to be 'index' now.
>>>      
>>>
>>Logically you are right, but I suspect that may not fly well in practice.  Too many of us have already got our fingers wired to type cache, and the glossary is there to describe both cache andindex.
>>    
>>
>
>I'd vote for cleaning it up /now/. Sure, it will hurt, but if you let time
>go by and do it later, it will hurt much more.
>
>Pre-1.0 is the last chance, AFAICS.
>  
>
I guess it all depends on whether your target audience is already using
it an happy with how it is, or whether your target audience is yet to
be reached.

Is git growing? Do we expect to suddenly find git upside down, where
there are a few old-timers awash in a sea of newbies? Do we care?

If you care, and git is growing, then probably it makes sense to
choose "the greatest good for the greatest number", I guess.

Personally, I'm a newbie and I find the command set confusing and
hard to internalize for reasons mostly dealing with naming, but also
because I don't have 6 months shared history with all of you. I have
to learn it partly from docs and partly through folklore gleaned from
the list (which moves pretty quickly).

Maybe that's just complaining, but maybe it is pointing out a
weakness that's correctable.

-- 
                             ><>
... either 'way ahead of the game, or 'way out in left field.

Re: Tool renames? was Re: First stab at glossary

[Junio C Hamano]

> By the way, I'm not sure how the 'git' script is supposed to be used.
> I know that if there is a git-foo-script file in your path, you can
> run it as 'git foo'.  But what about e.g. git-init-db?  You can run
> that as 'git init-db' today.  And 'git read-cache' should work too.
> And 'git ls-files', and 'git rev-parse', and 'git merge-one-file' and
> 'git sh-setup-script' in decreasing order of usefulness...
>
> But running 'git' without arguments only list the -script commands as
> available.

You are correct.  I think 'git' showing only *-script was done
as an attempt to give a list of Porcelainish commands, excluding
the core commands that people are not supposed to be typing from
the command line.  It so happened that all of the Porcelainish
commands were scripts.

But what Linus wants *-script to mean is editability in the
source tree (his "grep" and "em" examples).  The command being
Porcelainish and the command being implemented as a script tend
to have strong correlations, but in principle they are
orthogonal.  As you mention, 'git merge-one-file' is not really
useful standalone, neither is 'git sh-setup'.  On the other
hand, 'git fsck-cache' is.

My proposal to have git-archimport.perl in the source tree and
install it as $(bindir)/git-archimport solves the editability
issues (sorry, Linus, you will have to say "em *.sh *.perl"
instead of "em *-script" if we did this) and simplifies the
first half of the 'git' wrapper (it just needs to attempt
running "git-$1"), but does not help what the latter half of
'git' wrapper does (to give you the list of Porcelainish
commands).

To make 'git' wrapper produce useful 'list of subcommands', we
need to come up with a list of Porcelainish commands, be they
written in C or sh or Perl, and tell 'git' about that list.
Current implementation cheats by assuming everything that ends
with *-script are such, but it does not have to stay that way.

I'd nominate all $(SCRIPTS) in Makefile and tools/Makefile
except *1*, plus *2* as the list of subcommands 'git' wrapper
would show.

List *1*: implemented as script but not Porcelainish.
	git
        git-merge-one-file-script
        git-sh-setup-script

List *2*: implemented in C but Porcelainish.
	git-init-db
        git-fsck-cache
        git-get-tar-commit-id
        git-apply
        git-patch-id
        git-pack-objects
        git-show-branch

Tool renames.

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> My proposal to have git-archimport.perl in the source tree and
> install it as $(bindir)/git-archimport solves the editability
> issues (sorry, Linus, you will have to say "em *.sh *.perl"
> instead of "em *-script" if we did this) and simplifies the
> first half of the 'git' wrapper (it just needs to attempt
> running "git-$1"), but does not help what the latter half of
> 'git' wrapper does (to give you the list of Porcelainish
> commands).
>
> To make 'git' wrapper produce useful 'list of subcommands', we
> need to come up with a list of Porcelainish commands, be they
> written in C or sh or Perl, and tell 'git' about that list.
> Current implementation cheats by assuming everything that ends
> with *-script are such, but it does not have to stay that way.

I have done this and the first commit since 0.99.6 in the
proposed updates branch contains the big rename.

Re: Tool renames.

[H. Peter Anvin]

Junio C Hamano wrote:
> 
> I have done this and the first commit since 0.99.6 in the
> proposed updates branch contains the big rename.
> 

I noticed you also renamed git-ssh-{push,pull}.  These tools rely on 
having the same names on both sides, so you have introduced a major 
version skew problem.

	-hpa

Re: Tool renames.

[Junio C Hamano]

"H. Peter Anvin" <hpa@zytor.com> writes:

> I noticed you also renamed git-ssh-{push,pull}.  These tools rely on 
> having the same names on both sides, so you have introduced a major 
> version skew problem.

True.  It seems that both myself and Daniel did not think that
would be a major problem when we were discussing the tool
renames.

As a workaround, you could always say GIT_SSH_PULL='blah' and
GIT_SSH_PUSH='bah' when you run either side to name what will be
run on the other end.

Now the interesting problem is if we should rename these
environment variables ...

Re: Tool renames.

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> "H. Peter Anvin" <hpa@zytor.com> writes:
>
>> I noticed you also renamed git-ssh-{push,pull}.  These tools rely on 
>> having the same names on both sides, so you have introduced a major 
>> version skew problem.
>
> True.  It seems that both myself and Daniel did not think that
> would be a major problem when we were discussing the tool
> renames.
>
> As a workaround, you could always say GIT_SSH_PULL='blah' and
> GIT_SSH_PUSH='bah' when you run either side to name what will be
> run on the other end.

Come to think of it, I should be able to build git-ssh-push and
git-ssh-pull as fully backward compatible way to call the
counterpart with original name, instead of supplying just
symlinks the same way I do currently.  Let me work do that
before I do 0.99.7 this weekend.

> Now the interesting problem is if we should rename these
> environment variables ...

And the old and new binaries will be built separately anyway, I
could use GIT_SSH_FETCH and GIT_SSH_UPLOAD in the newname
binaries while keeping the old names in oldname binaries.  Ack?

Re: Tool renames.

[H. Peter Anvin]

Junio C Hamano wrote:
> 
> Come to think of it, I should be able to build git-ssh-push and
> git-ssh-pull as fully backward compatible way to call the
> counterpart with original name, instead of supplying just
> symlinks the same way I do currently.  Let me work do that
> before I do 0.99.7 this weekend.
> 

Better yet, always install the links, and have them use the *old* names 
when calling the remote end.

>>Now the interesting problem is if we should rename these
>>environment variables ...
> 
> And the old and new binaries will be built separately anyway, I
> could use GIT_SSH_FETCH and GIT_SSH_UPLOAD in the newname
> binaries while keeping the old names in oldname binaries.  Ack?

Urk.  Why do this rename anyway?

Typically when doing new environment variables like this you do:

	foo = getenv("NEW_NAME");
	if ( !foo )
		foo = getenv("OLD_NAME");

	-hpa

Re: Tool renames.

[Junio C Hamano]

"H. Peter Anvin" <hpa@zytor.com> writes:

> Urk.  Why do this rename anyway?

The "big rename"?  Or these two environment variables?

The former is because it was brought up by somebody who was
introduced to git not so long time ago (i.e. fingers not so
trained to use the old names and the brain wired to terminology
found in the glossary document) for consistency, with favorable
response from the git list.  The latter is just me feeling that
would make things more consistent.

As I outlined, if you keep using the git-ssh-{push,pull} names,
nothing should break.  They call each other using old names, and
0.99.7 will ship both new and old, so one end having 0.99.5 and
the other having 0.99.7 should not be a problem both ways.  The
same goes for those GIT_SSH_* environment variables -- backward
compatible commands honor environment variables with old names.

> Typically when doing new environment variables like this you do:

Yes that was what we did with the other old environment names,
but I can finally deprecate them in 0.99.7.

Initially I said 0.99.8 will stop supporting the old names
(including git-ssh-{push,pull}) and switch to new names only,
but I could be talked into carrying that beyond that, although I
have not heard any objections for that "dropping" plan since I
initially announced it when 0.99.6 was done.

But I personally prefer dropping the old names before we hit 1.0.