[PATCH/RFC] Add "first parent" to gitglossary

[PATCH/RFC] Add "first parent" to gitglossary

[Neal Kreitzinger]

Add "first parent" to "gitglossary" reference manual page.  Use the
definition provided by Junio Hamano in a git newsgroup post[1].

[1] http://article.gmane.org/gmane.comp.version-control.git/192523

Signed-off-by: Neal Kreitzinger <nkreitzinger@gmail.com>
Tested-by: Neal Kreitzinger <nkreitzinger@gmail.com>
---
Hi,

Why I did this patch:

I wanted to know for sure what "first parent" meant and not incorrectly
assume that I knew what it meant, and although I found it referenced
abundantly nowhere could I find it defined explicitly.

"first parent" is a git-ish term used often by git people, especially
by git gurus.  It even has its own option --first-parent for several git
commands.  However, the meaning of this term is never explicitly defined
in the documents that use it and the reader is left to infer the implied
meaning.  This glossary entry explicity defines the term in git-ish and
human-ish terms for mere mortals.

How I tested this patch in /home/me/git/.git master branch:

PWD=/home/me/git
$ git send-email ("from:" my linux user "to:" my linux user)
$ git reset --hard HEAD^
$ git am /var/spool/mail/me
$ gitk (commit looked right)
$ make doc
linux gui: "open with FireFox" for files:
/home/me/git/Documentation/gitglossary.html
/home/me/git/Documentation/user-manual.html
(IMO, they looked right)

I attempted to follow SubmittingPatches, and assume that the above test
is sufficient to ensure a properly formatted patch and to provide a 
"Tested-by:" tag (let me know otherwise).

v/r,
neal

 Documentation/glossary-content.txt |   24 ++++++++++++++++++++++++
 1 files changed, 24 insertions(+), 0 deletions(-)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 3595b58..d0abc7d 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -146,6 +146,30 @@ to point at the new commit.
 	i.e. the infrastructure to hold files and directories. That ensured the
 	efficiency and speed of git.
 
+[[def_first_parent]]first parent::
+	The mechanical definition of "first parent" is that:
++
+* A merge is a commit with more than one parent.
+* When you run "merge", you are on one commit, HEAD, taking changes
+made by "other brances" you are merging into "your history"
+(whose definition is "the commit-dag leading to your HEAD
+commit"), and record the resulting tree as a new commit.
+* This new commit records all its parents, one of them being your
+old "HEAD" and the rest being "other branches" you merged into
+"your history".  They are recorded in that order in the resulting
+commit ("git cat-file commit HEAD" after a merge to see them).
+
++
+Hence, the first parent of a merge is the HEAD the committer was at
+when he ran "git merge".
++
+Given the above definition, the first thing to realize is that "the
+first parent" is primarily a local concept.  If you are looking at
+one commit on a run of "a single strand of pearls", it only has one
+parent (i.e. its first parent), and it is the state the committer
+was on when he made the commit.  If you are looking at a merge, its
+first parent is the commit the person who made the merge was on.
+
 [[def_git_archive]]git archive::
 	Synonym for <<def_repository,repository>> (for arch people).
 
-- 
1.7.1

Re: [PATCH/RFC] Add "first parent" to gitglossary

[Junio C Hamano]

Neal Kreitzinger <nkreitzinger@gmail.com> writes:

> Add "first parent" to "gitglossary" reference manual page.  Use the
> definition provided by Junio Hamano in a git newsgroup post[1].
>
> [1] http://article.gmane.org/gmane.comp.version-control.git/192523

As the message was written specifically for you, taking what *you* seem to
already know, and more importantly what *you* seem to be misunderstanding,
into account, I do not think it is suitable for general documentation
without rewording.

Also, as Jonathan already pointed out, singling out "first parent" and
placing it in the glossary is a very odd thing to do.

Also see

  http://thread.gmane.org/gmane.comp.version-control.git/192427/focus=192534


Three entries "parent", "child" and "ancestry" might want to have an
explanation in the glossary to give new people the prerequisite, though.

child::
parent::
ancestry::
	Git represents a specific state of the project in its history with
	a commit object, which points at zero or more other commit objects
	as its "parents". When commit A points at commit B as its parent,
	we say "A is a child of B" and "B is a parent of A".
+
Parents of a commit is an ordered set, and because a commit object is
immutable, the parents of a commit do not change once it is created.
On the other hand, a new commit can be created, pointing at any other
commit as its parent, so children of a commit is not a mutable set,
and there is no inherent order among children.