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(-)
Show changes to Documentation/glossary-content.txt +24 −0
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
