# Re: [DRAFT] Branching and merging with git 10 messages from 2006-11-17 to 2006-11-26. Participants: linux@horizon.com, Junio C Hamano, Petr Baudis, J. Bruce Fields, Jakub Narebski, Robin Rosenberg. Thread: https://gitlist.dev/t/43312 ## J. Bruce Fields, 2006-11-17 18:21 Subject: Re: [DRAFT] Branching and merging with git Message-ID: <20061117182157.GC11882@fieldses.org> URL: https://gitlist.dev/e/20061117182157.GC11882%40fieldses.org In-Reply-To: <20061117153246.GA20065@thunk.org> ``` On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote: > Personally, I think this information is actually more important to an > end-user than the current "part two" of the tutorial, which discusses > the object database and the index file. Perhaps this should be "part > 2", and the object database and index file should become "part 3"? Yeah, the really difficult problem here is figuring out how to organize the documentation. There are a few needs: 1. Quick-start/task-based documentation - We want to "sell" git to the beginning user by getting them up and running as quickly as possible. - We need to help people with some limited needs-- testers who just need to download the latest linux git tree, or bisect, or whatever. - It's also a fun way to demonstrate the richness of some git features (e.g. history explanation). 2. Conceptual background - People need to understand the commit graph, branches, merging, the index file (gack), pack files, etc.--some of that can be put off a little while, some of it can't. 3. Reference documentation The man pages do most of #3, but maybe they could be better organized--I think people aren't finding stuff there that they should be. Numbers 1 and 2 are scattered around git(7), the two-part tutorial, the git-core tutorial, etc. > It might also be a good to consider moving some of the "discussion" > portion the top-level git(7) man page into the object database and > index file discussion. Right now, the best way to introduce git's > concepts (IMHO), is to start with the part 1 of the tutorial, then go > into the your draft branch/merging with git, then the current part 2 > of the tutorial, and then direct folks to read the "discussion" > section of git(7). Only then do they really have enough background > understanding of the fundamental concepts of git that they won't get > confused when they start talking to other git users, on the git > mailing list, for example. > > It would be nice if there was an easy way to direct users through the > documentation in a way which makes good pedagogical sense. Right now, > one of the reasons why life gets hard for new users is that the > current tutorials aren't enough for them to really undersatnd what's > going on at a conceptual level. And if users start using "everyday > git" as a crutch, without the right background concepts, the human > brain naturally tries to intuit what's happening in the background, > but without reading the background docs, git is different enough that > they will probably get it wrong, which means more stuff that they have > to unlearn later. I agree. Unfortunately, people who need to use git but aren't study-the-manual-first types *are* going to just dive in whether we want them to or not, so we have to make it easy for them to pick up what they need as they go. How about this as a strawman "git user's manual" outline: I. Quick-start: drawn from the tutorial part I and everyday.txt? II. Basic git concepts, drawn from "discussion" in git(7) (the README), tutorial part II, this branching-and-merging tutorial, etc.: 1. The commit graph and the object database 2. References 3. Fetching and pulling, remotes 4. The index file III. Using git: 1. History exploration 2. merge resolution 3. pack files, fsck, repository maintenance 4. pushing, setting up a public repo IV. Advanced examples: drawn from the howto directories, cvs-migration.txt,... 1. More complicated commandline magic, scripting (history exploration with git-rev-list, etc.) 2. History re-writing: cherry-picking, rebasing,... 3. Setting up a shared public repo? 4. Migration to/from other SCM's. IV. Technical details: core-tutorial.txt, plumbing, code tours, etc. Chapter II is the prerequisite for everything else, so a lot of thought has to be given to treating exactly what's necessary there and no more. Maybe more of it could be mixed into chapter I. It has to be readable in order by the 10% of people who actually like to read manuals, and easy to pick up in the middle for the 90% who will just dive into the section they were told they need to read to understand some particular problem. In particular, ideally only I and II would really be sequential, and the rest would be readable in any order. ``` ## linux@horizon.com, 2006-11-18 00:13 Subject: Re: [DRAFT] Branching and merging with git Message-ID: <20061118001355.23488.qmail@science.horizon.com> URL: https://gitlist.dev/e/20061118001355.23488.qmail%40science.horizon.com In-Reply-To: <20061117182157.GC11882@fieldses.org> ``` I'm working on incorporating all of the comments I've received, so thank you all! (BTW, the reason I didn't document git-describe is that I didn't know about it! You fixed the latter, so I'll fix the former.) I'm glad if others like it, but I was really scratching my own itch. I'm still wrapping my head around how to work with git, and writing this was my own learning experience. Even writing it out in full rather than as rougher notes wasn't an entirely unselfish act; it ensures: 1) I don't leave some important assumption unstated; that's the type most likely to be wrong, and 2) If I can get it good enough to post publicly, I'll get all the experts to fact-check it for me. As for the target audience, it's basically someone who's read git(1) and knows what a VCS is supposed to do, but has a CVS/SVN mindset. The emphasis is on branching and merging because that's the big "mental mode" difference in the way that git works. For anyone else documenting git, I recommend describing "what if I make a mistake" early. It was a bit of a revelation to realize that there's not much point to "git pull --no-commit" because it's so easy to undo. Just a couple of questions: We seem to have developed a consensus on the desirability of allowing HEAD to point outside refs/heads, postponing the check until commit/merge time. (At least, junkio and Linus seemed to like it.) I proposed it, so I get to write it, but you notice I have a whole section on how to work around the lack of that feature, so if someone feels like picking up the baton while I'm still writing docs, it would simplify things. I'd like to learn more about the zillion options to git-log. If people feel like sharing useful incantations, it would be be very helpful to give a concrete example of its usefulness, preferably within the git history itself. (Are there any octopus merges in git's history? If not, could I ask ``` ## Jakub Narebski, 2006-11-18 00:32 Subject: Re: [DRAFT] Branching and merging with git Message-ID: URL: https://gitlist.dev/e/ejlk82%24av5%241%40sea.gmane.org In-Reply-To: <20061118001355.23488.qmail@science.horizon.com> ``` linux@horizon.com wrote: [...] > (Are there any octopus merges in git's history? If not, could I ask > for one for pedagogical value?) See commit d425142e2a045a9dd7879d028ec68bd748df48a3 (most legged octopus I found in git.git repository). Doing git-rev-parse --parents -all, or git log --all and greppoing for merges is a good idea to find octopi. The commit is both v1.1.2-gd425142 (git describe) and tags/v1.2.0^0~143 (git name-rev --tags) -- Jakub Narebski Warsaw, Poland ShadeHawk on #git ``` ## Junio C Hamano, 2006-11-18 00:40 Subject: Re: [DRAFT] Branching and merging with git Message-ID: <7virhdh9j8.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7virhdh9j8.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <20061118001355.23488.qmail@science.horizon.com> ``` linux@horizon.com writes: > We seem to have developed a consensus on the desirability of allowing > HEAD to point outside refs/heads, postponing the check until > commit/merge time. (At least, junkio and Linus seemed to like it.) Yes, and I am actually interested in at least doing the initial damage assessment myself but people are welcome to beat me to it. The easies part would be to just try writing a bare SHA-1 to .git/HEAD with: H=$(git-rev-parse --verify HEAD) echo $H >.git/HEAD and see what breaks and start picking up the pieces from there. > I'd like to learn more about the zillion options to git-log. > If people feel like sharing useful incantations, it would be > be very helpful to give a concrete example of its usefulness, > preferably within the git history itself. > > (Are there any octopus merges in git's history? If not, could I ask > for one for pedagogical value?) git.git itself is full of them, but the very first octopus (it actually is a pentapus) is rather nice to watch in gitk: 211232bae64bcc60bbf5d1b5e5b2344c22ed767e You can look for them with: git rev-list --parents HEAD | grep '..* ..* ..* ..* ..* ..*' Repeat as many " ..*" as the number of parents you would want to require. I knew the very first one was pentapus (I did it) so I wrote six ..* there (one for the commit, one each for parents). Len's dodecapus in linux-2.6.git is this one: 9fdb62af92c741addbea15545f214a6e89460865 It is very interesting to watch it with "git show". Len has another one in August: da547d775fa9ba8d9dcaee7bc4e960540e2be576 ``` ## J. Bruce Fields, 2006-11-19 17:50 Subject: Re: [DRAFT] Branching and merging with git Message-ID: <20061119175040.GB15608@fieldses.org> URL: https://gitlist.dev/e/20061119175040.GB15608%40fieldses.org In-Reply-To: <20061117182157.GC11882@fieldses.org> ``` On Fri, Nov 17, 2006 at 01:21:57PM -0500, bfields wrote: > On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote: > > It would be nice if there was an easy way to direct users through the > > documentation in a way which makes good pedagogical sense. .... > How about this as a strawman "git user's manual" outline: In fact, I'm tempted to submit a patch that just assigns a chapter number to everything under Documentation/, slaps a single table of contents on the front, and calls the result "the git user's manual." Of course, the moment people started trying to read the thing they'd complain that it was a mess--some stuff referenced without being introduced, other stuff introduced too many times. But then over time maybe that'd force us to mold it into some sort of logical sequence. ``` ## Petr Baudis, 2006-11-19 17:59 Subject: Git manuals Message-ID: <20061119175952.GX7201@pasky.or.cz> URL: https://gitlist.dev/e/20061119175952.GX7201%40pasky.or.cz In-Reply-To: <20061119175040.GB15608@fieldses.org> ``` On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote: > On Fri, Nov 17, 2006 at 01:21:57PM -0500, bfields wrote: > > On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote: > > > It would be nice if there was an easy way to direct users through the > > > documentation in a way which makes good pedagogical sense. > .... > > How about this as a strawman "git user's manual" outline: (I was briefly discussing Git Book with Junio at OLS, I think the result was "yeah, would be nice, perhaps we can start poking it soon". I started to think about it once again in the last few weeks.) > In fact, I'm tempted to submit a patch that just assigns a chapter > number to everything under Documentation/, slaps a single table of > contents on the front, and calls the result "the git user's manual." > > Of course, the moment people started trying to read the thing they'd > complain that it was a mess--some stuff referenced without being > introduced, other stuff introduced too many times. But then over time > maybe that'd force us to mold it into some sort of logical sequence. Sequencing isn't the only problem. A _manual_ is different from _reference documentation_ in that it does not usually describe command after command, but rather concept after concept. So instead of slamming git-*-pack commands together, you have a section "Handling Packs" where you try to coherently describe the commands together. Your approach is fine for something you would call "Git Reference Manual", but it is something really different from "The Git Book" or "Git User's Manual". -- Petr "Pasky" Baudis Stuff: http://pasky.or.cz/ The meaning of Stonehenge in Traflamadorian, when viewed from above, is: "Replacement part being rushed with all possible speed." ``` ## Jakub Narebski, 2006-11-19 18:16 Subject: Re: Git manuals Message-ID: URL: https://gitlist.dev/e/ejq6ul%247co%241%40sea.gmane.org In-Reply-To: <20061119175952.GX7201@pasky.or.cz> ``` Petr Baudis wrote: > Your approach is fine for something you would call "Git Reference > Manual", but it is something really different from "The Git Book" or > "Git User's Manual". By the way, does AsciiDoc support conversion to texinfo (and then to info) format? It would be nice to have "The Git Book" aka "GUM - Git User's Manual" in texinfo, HTML and perhaps also PDF (HTML and PDF with graphs/images). -- Jakub Narebski Warsaw, Poland ShadeHawk on #git ``` ## J. Bruce Fields, 2006-11-19 19:36 Subject: Re: Git manuals Message-ID: <20061119193609.GA21866@fieldses.org> URL: https://gitlist.dev/e/20061119193609.GA21866%40fieldses.org In-Reply-To: <20061119175952.GX7201@pasky.or.cz> ``` On Sun, Nov 19, 2006 at 06:59:52PM +0100, Petr Baudis wrote: > On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote: > > In fact, I'm tempted to submit a patch that just assigns a chapter > > number to everything under Documentation/, slaps a single table of > > contents on the front, and calls the result "the git user's manual." > > > > Of course, the moment people started trying to read the thing they'd > > complain that it was a mess--some stuff referenced without being > > introduced, other stuff introduced too many times. But then over time > > maybe that'd force us to mold it into some sort of logical sequence. > > Sequencing isn't the only problem. A _manual_ is different from > _reference documentation_ in that it does not usually describe command > after command, but rather concept after concept. So instead of slamming > git-*-pack commands together, you have a section "Handling Packs" where > you try to coherently describe the commands together. > > Your approach is fine for something you would call "Git Reference > Manual", but it is something really different from "The Git Book" or > "Git User's Manual". Yeah, of course, but I wasn't actually thinking of the man pages so much as: everyday.txt tutorial.txt tutorial-2.txt core-tutorial.txt howto/ hooks.txt README glossary.txt etc. ``` ## Robin Rosenberg, 2006-11-19 19:50 Subject: Re: Git manuals Message-ID: <200611192050.52711.robin.rosenberg.lists@dewire.com> URL: https://gitlist.dev/e/200611192050.52711.robin.rosenberg.lists%40dewire.com In-Reply-To: ``` söndag 19 november 2006 19:16 skrev Jakub Narebski: > Petr Baudis wrote: > > Your approach is fine for something you would call "Git Reference > > Manual", but it is something really different from "The Git Book" or > > "Git User's Manual". > > By the way, does AsciiDoc support conversion to texinfo (and then to info) > format? It would be nice to have "The Git Book" aka "GUM - Git User's > Manual" in texinfo, HTML and perhaps also PDF (HTML and PDF with > graphs/images). Not sure if there is a texinfo translator, but HTML, PDF and anything else that DocBook can be used for is possible. ``` ## J. Bruce Fields, 2006-11-26 04:01 Subject: [PATCH] Documentation: add a "git user's manual" Message-ID: <20061126040142.GB3782@fieldses.org> URL: https://gitlist.dev/e/20061126040142.GB3782%40fieldses.org In-Reply-To: <20061119175040.GB15608@fieldses.org> ``` On Sun, Nov 19, 2006 at 12:50:40PM -0500, J. Bruce Fields wrote: > In fact, I'm tempted to submit a patch that just assigns a chapter > number to everything under Documentation/, slaps a single table of > contents on the front, and calls the result "the git user's manual." Something like this, as a start?: Add a manual.txt file which generates a "git user's manual" by including a bunch of preexisting files under Documentation and declaring each to be a chapter. The result is a disorganized mess, because the documentation itself is a disorganized mess. This is intended to call attention to that fact rather than fix it. Hopefully we can massage it into a better order over time. And hopefully we can encourage anyone that adds new documentation to think about where in the order it should be inserted. Not built or installed by default for now. Signed-off-by: J. Bruce Fields --- Documentation/Makefile | 7 ++++++- Documentation/manual.conf | 2 ++ Documentation/manual.txt | 30 ++++++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 1 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index c00f5f6..684dacf 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -85,9 +85,14 @@ clean: %.1 %.7 : %.xml xmlto -m callouts.xsl man $< -%.xml : %.txt +%.html : %.txt asciidoc -b docbook -d manpage -f asciidoc.conf $< +manual.html: manual.txt + a2x -f xhtml --no-icons --asciidoc-opts="-d book -f asciidoc.conf" $< + +# a2x -f xhtml --ascidoc-opts="-d book -f asciidoc.conf" $< + git.html: git.txt README glossary.html : glossary.txt sort_glossary.pl diff --git a/Documentation/manual.conf b/Documentation/manual.conf new file mode 100644 index 0000000..0d0cfad --- /dev/null +++ b/Documentation/manual.conf @@ -0,0 +1,2 @@ +[titles] +underlines="__","==","--","~~","^^" diff --git a/Documentation/manual.txt b/Documentation/manual.txt new file mode 100644 index 0000000..5512212 --- /dev/null +++ b/Documentation/manual.txt @@ -0,0 +1,30 @@ +Git User's manual +_________________ + +include::tutorial.txt[] + +include::tutorial-2.txt[] + +Git design overview +=================== + +include::README[] + +include::everyday.txt[] + +include::cvs-migration.txt[] + +include::howto-index.txt[] + +include::hooks.txt[] + +include::diffcore.txt[] + +include::repository-layout.txt[] + +include::core-tutorial.txt[] + +Glossary of git terms +===================== + +include::glossary.txt[] -- 1.4.4.rc1.g83ee9 ```