{"thread":{"id":"29974","subject":"[PATCH/RFC] Add \"first parent\" to gitglossary","startedAt":"2012-03-17T06:47:44Z","lastAt":"2012-03-18T18:56:41Z","messageCount":2,"participants":["Neal Kreitzinger","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"187136","messageId":"1331966864-31687-1-git-send-email-nkreitzinger@gmail.com","threadId":"29974","inReplyTo":null,"subject":"[PATCH/RFC] Add \"first parent\" to gitglossary","fromName":"Neal Kreitzinger","fromEmail":"nkreitzinger@gmail.com","sentAt":"2012-03-17T06:47:44Z","receivedAt":"2012-03-17T06:47:44Z","isPatch":true,"sender":{"key":"nkreitzinger@gmail.com","avatar":null},"body":"Add \"first parent\" to \"gitglossary\" reference manual page. Use the\ndefinition provided by Junio Hamano in a git newsgroup post[1].\n\n[1] http://article.gmane.org/gmane.comp.version-control.git/192523\n\nSigned-off-by: Neal Kreitzinger \nTested-by: Neal Kreitzinger \n---\nHi,\n\nWhy I did this patch:\n\nI wanted to know for sure what \"first parent\" meant and not incorrectly\nassume that I knew what it meant, and although I found it referenced\nabundantly nowhere could I find it defined explicitly.\n\n\"first parent\" is a git-ish term used often by git people, especially\nby git gurus. It even has its own option --first-parent for several git\ncommands. However, the meaning of this term is never explicitly defined\nin the documents that use it and the reader is left to infer the implied\nmeaning. This glossary entry explicity defines the term in git-ish and\nhuman-ish terms for mere mortals.\n\nHow I tested this patch in /home/me/git/.git master branch:\n\nPWD=/home/me/git\n$ git send-email (\"from:\" my linux user \"to:\" my linux user)\n$ git reset --hard HEAD^\n$ git am /var/spool/mail/me\n$ gitk (commit looked right)\n$ make doc\nlinux gui: \"open with FireFox\" for files:\n/home/me/git/Documentation/gitglossary.html\n/home/me/git/Documentation/user-manual.html\n(IMO, they looked right)\n\nI attempted to follow SubmittingPatches, and assume that the above test\nis sufficient to ensure a properly formatted patch and to provide a \n\"Tested-by:\" tag (let me know otherwise).\n\nv/r,\nneal\n\n Documentation/glossary-content.txt | 24 ++++++++++++++++++++++++\n 1 files changed, 24 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 3595b58..d0abc7d 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -146,6 +146,30 @@ to point at the new commit.\n \ti.e. the infrastructure to hold files and directories. That ensured the\n \tefficiency and speed of git.\n \n+[[def_first_parent]]first parent::\n+\tThe mechanical definition of \"first parent\" is that:\n++\n+* A merge is a commit with more than one parent.\n+* When you run \"merge\", you are on one commit, HEAD, taking changes\n+made by \"other brances\" you are merging into \"your history\"\n+(whose definition is \"the commit-dag leading to your HEAD\n+commit\"), and record the resulting tree as a new commit.\n+* This new commit records all its parents, one of them being your\n+old \"HEAD\" and the rest being \"other branches\" you merged into\n+\"your history\". They are recorded in that order in the resulting\n+commit (\"git cat-file commit HEAD\" after a merge to see them).\n+\n++\n+Hence, the first parent of a merge is the HEAD the committer was at\n+when he ran \"git merge\".\n++\n+Given the above definition, the first thing to realize is that \"the\n+first parent\" is primarily a local concept. If you are looking at\n+one commit on a run of \"a single strand of pearls\", it only has one\n+parent (i.e. its first parent), and it is the state the committer\n+was on when he made the commit. If you are looking at a merge, its\n+first parent is the commit the person who made the merge was on.\n+\n [[def_git_archive]]git archive::\n \tSynonym for <> (for arch people).\n \n-- \n1.7.1\n"},{"id":"187212","messageId":"7vehspd9g6.fsf@alter.siamese.dyndns.org","threadId":"29974","inReplyTo":"1331966864-31687-1-git-send-email-nkreitzinger@gmail.com","subject":"Re: [PATCH/RFC] Add \"first parent\" to gitglossary","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-18T18:56:41Z","receivedAt":"2012-03-18T18:56:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Neal Kreitzinger writes:\n\n> Add \"first parent\" to \"gitglossary\" reference manual page. Use the\n> definition provided by Junio Hamano in a git newsgroup post[1].\n>\n> [1] http://article.gmane.org/gmane.comp.version-control.git/192523\n\nAs the message was written specifically for you, taking what *you* seem to\nalready know, and more importantly what *you* seem to be misunderstanding,\ninto account, I do not think it is suitable for general documentation\nwithout rewording.\n\nAlso, as Jonathan already pointed out, singling out \"first parent\" and\nplacing it in the glossary is a very odd thing to do.\n\nAlso see\n\n http://thread.gmane.org/gmane.comp.version-control.git/192427/focus=192534\n\n\nThree entries \"parent\", \"child\" and \"ancestry\" might want to have an\nexplanation in the glossary to give new people the prerequisite, though.\n\nchild::\nparent::\nancestry::\n\tGit represents a specific state of the project in its history with\n\ta commit object, which points at zero or more other commit objects\n\tas its \"parents\". When commit A points at commit B as its parent,\n\twe say \"A is a child of B\" and \"B is a parent of A\".\n+\nParents of a commit is an ordered set, and because a commit object is\nimmutable, the parents of a commit do not change once it is created.\nOn the other hand, a new commit can be created, pointing at any other\ncommit as its parent, so children of a commit is not a mutable set,\nand there is no inherent order among children.\n"}]}