Skip to contentSkip to conversation

Add a few more words to the glossary.

PATCH In review Jon Loeliger 2 participants 3 messages Jun 15, 2016 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 3/3 Add a few more words to the glossary.

Clean up a few entries and fix typos.

bare repository
cherry-picking
hook
symbolic ref
topic branch

---

 Documentation/glossary.txt |   68 ++++++++++++++++++++++++++++++++++++--------
 1 files changed, 55 insertions(+), 13 deletions(-)

b7524dc93e17807a3657f017adcbe129e16c4b94

Documentation/glossary.txt +55 -13
index 86196c4..f166d4f 100644
@@ -3,6 +3,17 @@ alternate object database::
 	object database from another object database, which is called
 	"alternate".
 
+bare repository::
+	A bare repository is normally an appropriately 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
+	hidden `.git` sub-directory are directly present in
+	the `repository.git` directory instead, and no other files
+	are present and checked out.  Usually publishers of public
+	repositories make bare repositories available.
+
 blob object::
 	Untyped object, e.g. the contents of a file.
 
@@ -28,6 +39,15 @@ checkout::
 	The action of updating the working tree to a revision which was
 	stored in the object database.
 
+cherry-picking::
+	In SCM jargon, "cherry pick" means to choose a subset of
+	changes out of a series of changes (typically commits)
+	and record them as a new series of changes on top of
+	different codebase.  In GIT, this is performed by
+	"git cherry-pick" command to extract the change
+	introduced by an existing commit and to record it based
+	on the tip of the current branch as a new commit.
+
 clean::
 	A working tree is clean, if it corresponds to the revision
 	referenced by the current head.  Also see "dirty".
@@ -100,6 +120,16 @@ head ref::
 	A ref pointing to a head. Often, this is abbreviated to "head".
 	Head refs are stored in `$GIT_DIR/refs/heads/`.
 
+hook::
+	During the normal execution of several git commands,
+	call-outs are made to optional scripts that allow
+	a developer to add functionality or checking.
+	Typically, the hooks allow for a command to be pre-verified
+	and potentially aborted, and allow for a post-notification
+	after the operation is done.
+	The hook scripts are found in the `$GIT_DIR/hooks/` directory,
+	and are enabled by simply making them executable.
+
 index::
 	A collection of files with stat information, whose contents are
 	stored as objects. The index is a stored version of your working
@@ -113,10 +143,10 @@ index entry::
 	that file).
 
 master::
-	The default branch. Whenever you create a git repository, a branch
-	named "master" is created, and becomes the active branch. In most
-	cases, this contains the local development.
-
+	The default development branch. Whenever you create a git
+	repository, a branch named "master" is created, and becomes
+	the active branch. In most cases, this contains the local
+	development, though that is purely conventional and not required.
 
 merge::
 	To merge branches means to try to accumulate the changes since a
@@ -151,10 +181,11 @@ octopus::
 	predator.
 
 origin::
-	The default upstream branch. Most projects have one upstream
-	project which they track, and by default 'origin' is used for
-	that purpose.  New updates from upstream will be fetched into
-	this branch; you should never commit to it yourself.
+	The default upstream tracking branch. Most projects have at
+	least one upstream project which they track. By default
+	'origin' is used for that purpose.  New upstream updates
+	will be fetched into this branch; you should never commit
+	to it yourself.
 
 pack::
 	A set of objects which have been compressed into one file (to save
@@ -168,7 +199,8 @@ parent::
 	A commit object contains a (possibly empty) list of the logical
 	predecessor(s) in the line of development, i.e. its parents.
 
-pickaxe:: The term pickaxe refers to an option to the diffcore routines
+pickaxe::
+	The term pickaxe refers to an option to the diffcore routines
 	that help select changes that add or delete a given text string.
 	With the --pickaxe-all option, it can be used to view the
 	full changeset that introduced or removed, say, a particular
@@ -204,8 +236,8 @@ rebase::
 	changes from that branch.
 
 ref::
-	A 40-byte hex representation of a SHA1 pointing to a particular
-	object. These may be stored in `$GIT_DIR/refs/`.
+	A 40-byte hex representation of a SHA1 or a name that denotes
+	a particular object. These may be stored in `$GIT_DIR/refs/`.
 
 refspec::
 	A refspec is used by fetch and push to describe the mapping
@@ -243,10 +275,20 @@ SCM::
 SHA1::
 	Synonym for object name.
 
+symbolic ref::
+	See "ref".
+
+topic branch::
+	A regular git branch that is used by a developer to
+	identify a conceptual line of development.  Since branches
+	are very easy and inexpensive, it is often desirable to
+	have several small branches that each contain very well
+	defined concepts or small incremental yet related changes.
+
 tracking branch::
-	A regular git branch that is used to follow changes from
+	A regular git branch that is used to follow changes frompointing
 	another repository.  A tracking branch should not contain
-	direct modifications or made commits made locally.
+	direct modifications or have local commits made to it.
 	A tracking branch can usually be identified as the
 	right-hand-side ref in a Pull: refspec.
 
Signature · 1 line
1.3.1.g3d990
#1 lore raw

Documentation/glossary.txt rebase::

Quoted 8 lines · Jon Loeliger

ref::

Documentation/glossary.txt +4 -2
-	A 40-byte hex representation of a SHA1 pointing to a particular
-	object. These may be stored in `$GIT_DIR/refs/`.
+	A 40-byte hex representation of a SHA1 or a name that denotes
+	a particular object. These may be stored in `$GIT_DIR/refs/`.
 
+symbolic ref::
+	See "ref".

Uum. Not very clear. Do we use that word that often?

I think I used that term to differenciate between HEAD symlink pointing at refs/heads/master and HEAD being a regular file that stores a line "ref: refs/heads/master\n"; the latter is the modern style "textual symref", so in that context it is not about 40-byte hex at all. And at that level it is really a jargon to talk about one small implementation detail of HEAD, so I am not sure it deserves to be in the glossary.

Documentation/glossary.txt SCM:: · line 290

Quoted 4 lines

tracking branch::

Documentation/glossary.txt +1 -1
-	A regular git branch that is used to follow changes from
+	A regular git branch that is used to follow changes frompointing
 	another repository.  A tracking branch should not contain

I think this is a typo?

#2 lore raw

So, like, the other day Junio C Hamano mumbled:

Quoted 10 lines

Documentation/glossary.txt rebase:: · line 240

Quoted 6 lines · Jon Loeliger

ref::

Documentation/glossary.txt +2 -2
-	A 40-byte hex representation of a SHA1 pointing to a particular
-	object. These may be stored in `$GIT_DIR/refs/`.
+	A 40-byte hex representation of a SHA1 or a name that denotes
+	a particular object. These may be stored in `$GIT_DIR/refs/`.

Uum. Not very clear. Do we use that word that often?

Well, I was mystified a bit too, and I tried to clean it up some... "ref" gets used as half a <refspec>, from pull-fetch-param.txt:

A parameter <ref> without a colon is equivalent to <ref>: when pulling/fetching, so it merges <ref> into the current branch without storing the remote branch anywhere locally

So maybe I was confused here.

Quoted 10 lines

Documentation/glossary.txt SCM:: · line 279

Quoted 2 lines
Documentation/glossary.txt +2 -0
+symbolic ref::
+	See "ref".

I think I used that term to differenciate between HEAD symlink pointing at refs/heads/master and HEAD being a regular file that stores a line "ref: refs/heads/master\n"; the latter is the modern style "textual symref", so in that context it is not about 40-byte hex at all. And at that level it is really a jargon to talk about one small implementation detail of HEAD, so I am not sure it deserves to be in the glossary.

Given "git-symbolic-ref <name> [<ref>]", clearly I just botched it. You were right to drop my confused "symbolic ref" entry. :-(

Quoted 6 lines

Documentation/glossary.txt SCM:: · line 290

Quoted 4 lines

tracking branch::

Documentation/glossary.txt +1 -1
-	A regular git branch that is used to follow changes from
+	A regular git branch that is used to follow changes frompointing
 	another repository.  A tracking branch should not contain

I think this is a typo?

Yes. Thanks for noticing and cleaning.

jdl