I know it took me a while to get used to playing with branches, and I
still get nervous when doing something creative.  So I've been trying
to get more comfortable, and wrote the following to document what I've
learned.

It's a first draft - I just finished writing it, so there are probably
some glaring errors - but I thought it might be of interest anyway.


* Branching and merging in git

In CVS, branches are difficult and awkward to use, and generally
considered an advanced technique.  Many people use CVS for a long time
without departing from the trunk.

Git is very different.  Branching and merging are central to effective use
of git, and if you aren't comfortable with them, you won't be comfortable
with git.  In particular, they are required to share work with other
people.

The only things that are a bit confusing are some of the names.
In particular, at least when beginning:
- You create new branches with "git checkout -b".
  "git branch" should only be used to list and delete branches.
- You share work with "git fetch" and "git push".  These are opposites.
- You merge with "git pull", not "git merge".  "git pull" can
  also do a "git fetch", but that's optional.  What's not optional
  is the merge.


* A brief digression on command names.

Originally, all git commands were named "git-foo".  When there got to
be over a hundred, people started complaining about the clutter in
/usr/bin.  After some discussion, the following solution was reached:

- It's now possible to place all of the git-foo commands into a separate
  directory.  (Despite the complaints, not too many people are doing it
  yet.)
- One option for git users is to add that directory to their $PATH.
- Another is provided by a wrapper called just "git".  It's intended to
  live in a public directory like /usr/bin, and knows the location of
  the separate directory.  When you type "git foo", it finds and executes
  "git-foo".
- Some simple commands are built into the git wrapper.  When you type
  ...
[ message continues ]

This is a greatest write-up I've seen for the past several
months.  I find it very balanced to point out the quirks people
would find difficult and explain why things are so by including
historical notes in appropriate places when needed.  Definitely
Documentation/ material when copyediting is done.

I have finished only the first half because it's not my git day

You might want to check this with the array in sha1_name.c::get_sha1_basic().

It's great that you talk correctly about the latest feature-fix


I think you wanted to mention .git/refs/remotes hierarchy and

refs/tags namespace is not policed at all by git and is treated
as a global namespace, controlled mostly by social convention
that your "upstream" (or central distribution point) supplies
tags for people who use it to synchronize to share.  Also, since
there is no guarantee that tags point at commits (v2.6.11-tree
tag is a pointer to a tree object, for example), there is no
farst-forward check performed for them.

The rule we use to autofollow tags currently is:

When you use shorthand fetch (or pull), we find tags that do not
exist locally, and if the object they point at are already found
in the repository then we fetch them automatically.  So for
example, if you are only tracking my 'maint' and not 'master'
nor 'next', and if you have tags up to v1.4.3.2, your "git fetch
origin" would update your copy of 'maint' and bring the commits
reachable from the tip of my 'maint'.  After that it notices
that v1.4.3.3, v1.4.3.4, v1.4.3.5 tags are in my repository but
missing from yours. It also notices that now you have
v1.4.3.3^{}, v1.4.3.4^{} and v1.4.3.5^{} in your repository, so
it issues another round of "git fetch" internally to fetch these
three tags.  At the same time it would also notice that I have
v1.4.4 tag that you do not have, but v1.4.4^0 commit is not
something you would get by fetching 'maint', so it would not
fetch it automatically.

-

[ message continues ]

I'm trying; I've been following git since day 1, so occasionally an
obsolete fact gets stuck in my head.

If anyone has any advice on how and why one would invoke git-merge
directly (the one why I know is to do a >2-way merge), that would


Quite right.  It's

        static const char *fmt[] = {
                "%.*s",
                "refs/%.*s",
                "refs/tags/%.*s",
                "refs/heads/%.*s",
                "refs/remotes/%.*s",
                "refs/remotes/%.*s/HEAD",
                NULL


Ah, yes, I added include/scsi to the example to illustrate how

Yes, sorry.  I meant to research that and update this (I've never used

Ah, okay.  Actually, v2.6.11-tree is a tag object
(5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c) which points
to a tree object (c39ae07f393806ccf406ef966e9a15afc43cc36a).

I was wondering if git only shared refs/tags that pointed to
heavyweight tag objects and not lightweight tags.

That appears to be the case:

mkdir a b
cd a
git-init-db
echo "Hello, world" > hello
git add hello
git commit -m "Initial commit"
git tag light
git tag -a -m "Test tag" heavy
cd ../b
git-init-db
echo "URL: ../a" > .git/remotes/a
echo "Pull: master:origin" >> .git/remotes/a
git fetch a

But!  It only fetches tags if you specify a destination branch name.
I hadn't noticed that before, but "git-fetch <url> foo" and
"git-fetch <url> foo:foo" do different things on the receiver.
Didn't they used to be synonyms?
(I think it's a net gain in flexibility.)

Oh!  Also, the git-pull man page says that multiple branch names are
allowed, even though the SYNOPSIS line says no.

I also need to mention that if you want to pull a remote tag,
you need to prefix it with "tags/".  For some reason, the search
path is different.
-

[ message continues ]

I use "git pull . topicA topicB" for a tetrapus, so that is not
a reason for me, but when a topicA's older parts are worthy to
be in 'next' while later parts are not yet, I often do (on 'next'):


	git merge "Merge early part of branch 'topicA'" HEAD topicA~3

Also I used to do

	git merge fast HEAD someTopicIknowIsAFastForward

because it felt faster than "git pull . someTopicIknowisAFastForward"

I do not think naming a directory (say, ".") to mean "revert
everything underneath this directory" worked until the patch I

Yes, recent -mm announce message says "git pull ... tag v2.x-mmY".
"tag v2.x-mmy" is a shorthand for "refs/tags/v2.x-mmY:refs/tags/v2.x-mmY"


-

[ message continues ]

This is a very important point to remember not for users but for


It is not "somewhere" but "in the current branch", so in a sense
it is a bit stricter than that.  While on 'master' "branch -d
topic" would not remove the topic branch head if it is not fully
merged to my 'master' so that is a reasonable safety measure,
but when I am on 'next' it will happily remove it.  It is

One bug in my previous response is that I said we do this only
when the command was invoked with shorthand remote name.  Not
so.  We do this only when we use tracking branches.

The reason is because 'git pull $url $branch' (typical Linus's
use) and 'git pull' (defaulting to 'origin' and using the
tracking branch mapping stored in .git/remotes/origin prepared
by git-clone) are sign of very different workflows.  The former
tends to be a one-shot event while the latter is most often
synchronizing with either an upstream or a common distribution
point (i.e. shared central repostiory).  When you are fetching
from somebody in a one-shot manner, most likely as a part of
'pull', you do not want to get the tag the other person has made
to mark his private work in progress.  But in the latter case,
the other end is where everybody who works in the same area
fetches from, and sharing the tags found there among the
developers by default is desirable, and more importantly there
is no risk of accidentally getting private tags, since the other
end is a public distribution point and by definition should not

Here you _might_ want to mention an alternative workflow that
uses rebase, which seems to be the way Wine folks run their
project.  Talking about all the different possibilities tends to
cloud things and may not add value to the document, so I am just
mentioning it as a possibility but I do not know if talking

This is not true; "git pull . topicA topicB topicC" works as
expected.  But we probably would not want to even talk about
Octopus in a document like this.  It is a curosity, and
sometimes tends to ...
[ message continues ]

Overall, thank you.  I'm trying to merge all your comments
into the document to make it better, but there are enough that

There's a great example coming up, in the git-show


Oh!  Thanks for the info.  The limitation makes a certain
amount of sense, and as I'd never run into it, I'm not going to







I figured the (excellent) pictures in git-rebase would save me the


I'm wondering what the heck that does!  I get a super-short diff with
no mention of any renames at all.  Is this passed on to git-diff-tree?
What does "detect renames" mean if it doesn't tell me about them?
I'm actually confused.

diff --cc builtin-read-tree.c
index ec40d01,99e7c75..716f792
--- a/builtin-read-tree.c
+++ b/builtin-read-tree.c
@@@ -9,9 -9,9 +9,10 @@@
  
  #include "object.h"
  #include "tree.h"
+ #include "cache-tree.h"
  #include <sys/time.h>
  #include <signal.h>
 +#include "builtin.h"
  
  static int reset = 0;
  static int merge = 0;
-

[ message continues ]

Of course "git log -p --merge -- $path" would give the patch

"show $merge" is really "diff-tree --cc -p $merge".  So first I
should (not necessarily "you should to the readers of this
document") talk about three ways to describe a merge commit with
textual diffs.

(1) N independent diffs between each of the parents and the child.

    We could get this with

    	git diff-tree -m -p $merge

    but it is mostly useless, because very often many paths in a
    merge are truly trivial and the version from one of the
    parents is taken verbatim, whole file.  When looking at the
    development history, the real reason of the change is found
    in earlier log for that parent, and not in the merge in
    question.

    The diff between the child and its first parent is somewhat
    useful, because it represents the damage inflicted on his
    branch the person saw when he made the merge.  For this
    reason, "--stat" gives the graph for the first-parent diff
    for a merge.  But otherwise "diff-tree -p" by default stays
    silent about merges because it is not that useful, and that
    is why the above asks for the "useless output ;-)" with an
    explicit "-m".

(2) Uncompressed "combined diff" between all parents and the child.

    We can get this with:

	git diff-tree -c -p $merge

    This gives a combined diff that shows all the files parents
    and child disagreed (in other words, if the resulting file
    matches verbatim with one of the parents, it is not shown).
    This is already useful by reducing the clutter of truly
    trivial merges, compared to (1) above, but most clean merges
    take either first or second parent's version verbatim for
    each hunk (but not necessarily taking all hunks from the
    same parent) and these hunks are not very interesting.

    Because "-c" explicitly tells something special to be done
    for a merge, you do not need to say "-m" for the above
    command (giving -m does not hurt, but is not necessary).
    ...
[ message continues ]

This is really, really good stuff that you've written!  Have you any
thoughts or suggestions about where this text should end up?
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"?  

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

Hmm... this assumes that you've read the Git(7) discussion first.
There is enough information here though that maybe you don't need to
say "as you recall".  It might be enough to give a quick summary of
the concepts that are needed to understand the rest of your tutorial,
and then point to git(7) Discussion section for people who need ...
[ message continues ]

On Fri, 17 Nov 2006 10:32:46 -0500

It would be nice to post this information on the Git website and not
have it overshadowed by Cogito examples with paragraphs explaining how
Cogito makes things easier.  The current website distracts users away
from learning Git or ever reading about this kind of information.
Maybe we can pass a hat around for some funds for a separate Cogito
 
That's quite a good idea.  The name was fixed when the option to move
this info into the config file was added (remote.<name>.fetch).  So
another option would be to show new users the config file method and
just damn the remotes file to a historical footnote.

Sean
-

[ message continues ]

Or.. find a way to merge cogito back to git :-)
/me runs into a nearest bush.
-- 
Duy
-

[ message continues ]

I agree, this would certainly be the best solution. But it would imply
hiding the 'index' by default which would probably an incompatible change.

The alternative would be to explain that git is a low level tool suitable 
mostly for integrators like Linus (that, and that Cogito and/or StGit should 
be used by developers/contributors).

Mark
-

[ message continues ]

I think we are trying to figure that out in the last few days in those
mammoth threads. UI-wise with no big breakthroughs so far I guess,

This is in essence what many people (including Junio) are saying. I'm
not saying it's a totally great situation, hence the previous paragraph.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1
lK[d2%Sa2/d0$^Ixp"|dc`;s/\W//g;$_=pack('H*',/((..)*)$/)
-

[ message continues ]

On Fri, 17 Nov 2006 23:19:23 +0700

Pasky has already given a lot to Git, and it would be great to see even
more merged back into Git where a consensus can be reached.  In fact
Pasky has said that his plan is to push a lot more towards Git and
make Cogito a thinner UI layer.  Either way, there's absolutely nothing
wrong with people choosing to use Cogito rather than Git.  It's just
that the separate Cogito tool shouldn't have a place on the Git website
any more prominent than say StGit does.

The Git website should be a place where Git makes the best case
it can for _itself_, not for its sister tools.  It's a distraction
and gets in the way of promoting Git as a stand alone tool.  At
least one new user has complained that it was confusing.

Personally I have nothing against Cogito, I just think Pasky should
separate his role as Git webmaster from his role as Cogito author.
If people have good ideas for Git documentation, the website would be
a natural place for it, and it shouldn't have to compete with Cogito
tutorials etc.

Sean
-

[ message continues ]

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

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 ...
[ message continues ]

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
for one for pedagogical value?)
-

[ message continues ]

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


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


-

[ message continues ]

Having said that, I think it is not a good idea to talk about
octopus in introductory documents.  The 'feature' may be unique
to git and some people might even find it cool, but new people
should not be encouraged to use it until they understand the
ramifications.

The first ever octopus merge was just a bundle of five forked
development branches, each of which had only one commit since it
forked from the common parent.

           .-a-.  
          .--b--.
         O---c---X
          '--d--'
           '-e-' 

They were independent, un-overlapping changes.  "diff-tree -c"
would not show anything, and there was no inherent reason that
one change should come before the others, so in that sense,
presenting this as an octopus was making the history more
truthful than pretending one happened before another.

But octopus has a negative effect on bisecting performance.
Suppose commit X was bad and commit O was good.  Because X
bundles five branches into one, and we know one of them
(hopefully) is what introduced the regression, our task is to
find the guilty one commit among five commits.  But in order to
do so, we would end up having to test four commits.  That is,
knowing that a, b and c are Ok does not give us any useful
information to determine which of d or e is the bad one (after
learning that a, b and c are Ok, we still need to test d and if
it turns out to be Ok then we can finally say e is the bad one).

If I did not do an octopus and laid out the commit ancestry
graph this way when I gave them to Linus:

    O--a--b--c--d--e--X

the same bisect would have asked us check c first.  If it is
good, then we do not even have to test a or b.  The linear part
of the history is what bisect takes advantage of to cut the
search space efficiently, and an octopus actively defeats that.

So doing an octopus is a wrong thing to do, if there is a
possibility that something wrong is found later.  So people
should not do an octopus unless the component changes are all
truely ...
[ message continues ]

I tried to incorporate all the suggestions.  There are still a few things
I have to research, and now I'm worried it's getting too long.  Sigh.

Generally, it's wonderful when the whole is greater than the sum of
the parts.  But trying to explain that is difficult, because you have
to explain all the parts before you can explain how they work together
to deliver a feature.

Oh, well.  Perhaps I can rearrange this to talk about remote branches
*after* local merging?

Thanks to everyone who commented.


* Branching and merging in git

In CVS, branches are difficult and awkward to use, and generally
considered an advanced technique.  Many people use CVS for a long time
without departing from the trunk.

Git is very different.  Branching and merging are central to effective use
of git, and if you aren't comfortable with them, you won't be comfortable
with git.  In particular, they are required to share work with other
people.

The only things that are a bit confusing are some of the names.
In particular, at least when beginning:
- You create new branches with "git checkout -b".
  "git branch" should only be used to list and delete branches.
- You share work with "git fetch" and "git push".  These are opposites.
- You merge with "git pull", not "git merge".  "git pull" can also do a
  "git fetch", but that's optional.  What's not optional is the merge.

Also, a good habit it to never commit directly to your main "master"
branch.  Do all work in temporary "topic" branches, and then merge them
into the master.  Most experienced users don't bother to be quite this
purist, but you should err on the side of using separate topic branches,
so it's excellent practice.


* A brief digression on command names

All git commands can be invoked as "git-foo" and "git foo".  This document
uses them interchangably.  But you have to ask for the "git-foo" man page.
Git provides a few other ways to get the man page as well:
	man git-foo
	git help foo
	git foo --help

Git doesn't have ...
[ message continues ]

If you made another pass for it asking whether each sentence was really
absolutely necessary you'd be able to cut quite a bit without

Lots of people have CVS experience, but not everyone does, and this
paragraph isn't really necessary.  Cut it out, and the following

Note also "if you aren't comfortable with them..." just repeats
something you've already said.  So now we're down to just:

	"Branching and merging are central to effective use of git.  In
	particular, they are required to share work with other people."

which is short and to the point.  Neat!


We're diving in here without explaining what checkout, fetch, push,
pull, or merge are yet, or what the master branch is.

The document seems to be targetted at someone who has read some
scattered git documentation, gotten confused, and needs help putting it
all together.  This is understandable--there are a lot of people like
that right now!  But if we're going to get the documentation in some
sort of sensible order then we need to think about how to start with
someone who is a blank slate and lead them step by step to what they
most need to know.

That doesn't mean *you* need to do everything from scratch, but it would
be helpful to figure out where this would fit in with the other
documentation in a logical progression.  As a start, the first paragraph
could say "before reading this, we assume you've read X, Y, and Z", and
then the rest of the document could be audited to make sure that it
didn't assume anything that isn't in X, Y, and Z.

--b.
-

[ message continues ]

By the way, I have some draft rough work on getting that introductory
documentation organized at

	git://linux-nfs.org/~bfields/git.git

See Documentation/user-manual.txt and Documentation/quick-start.txt.  I
think I've stolen a small amount of text from you--hope that's OK!

I have two ideas in mind:

	- The tutorial is supposed to a very quick "look what git can
	  do" document, but people also want it to really explain git,
	  prepare people to read the man pages, etc., which will make it
	  much longer over time.  So I'm trying to split out an
	  extremely concise "quick-start" guide (modelled partly on
	  Mercurial's) that doesn't even pretend to explain anything, and
	  a "user manual" that's much more verbose and tries to cover
	  the basics comprehensively.

	- A lot of people don't actually need to do commits or merges at
	  all--they just need to know how to clone a repository, check
	  out a few versions, etc.  (Witness the number of web pages
	  with "how to check out our latest code from CVS" out
	  there....) I'm also assuming most people are joining an
	  ongoing project instead of creating a new one.  So instead of
	  starting right away with init-db/add/commit, I'm putting off
	  actual "development" stuff till pretty late:

	  	1. clone
		2. checking out old versions, basic branch management
		3. keeping up-to-date with fetch
		4. bisect
		5. archaeology (commits DAG, git-log, ...)
		6. creating commits, index file
		7. resolving merges, pull
		8. publishing a public repository, push

	  etc.  I'm hoping you'd be interested in working together on
	  the last parts (7 and 8 especially).

Comments welcomed...

--b.
-

[ message continues ]

Hi,



Another approach would be to illustrate short stories of a failed merge, 
or "how I put up a public repository", etc. Like, more example-based (and 
of course short enough that people actually read through it).

Ciao,
Dscho

-

[ message continues ]

I actually remembered a better one.

        Subject: Necessity of "evil" merge and topic branches
        Date: Wed, 17 May 2006 23:25:55 -0700
        Message-ID: <7vy7wz6e8c.fsf@assigned-by-dhcp.cox.net>

This talks about a real-world evil merge and the reason why it
was necessary, and speculates a possible way to make life
easier.  I actually later used the "third branch to remember the
evil merge between two topics" technique I talked about in the
message to merge in another pair of topics, and it turned out
that it worked rather well.

There were two logically independent topics:

 - lt/setup.  Two commits, changing the calling convention of
   setup_git_directory() function -- the final tip of the topic
   was at a633fca0.

 - js/mv.  Three commits, making git-mv a built-in after
   refactoring some code from other parts of the system -- the
   final tip of the topic was at ac64a722).

They were not "obviously correct" when they started, so a topic
branch was used for each.  They had textually and semantically
some conflicts, and if they were to progress at different paces,
there was a need for an evil merge when the later one is merged
to master.

So I created another branch to merge the two topics together and
resolved their conflicts while my reading of their code were
still fresh.

	git checkout -b __/setup-n-mv js/mv
        git pull . lt/setup
	git checkout next
        git pull . __/setup-n-mv

Later js/mv became ready to be merged first.  So I merged it to
'master'.

	git checkout master
        git pull . js/mv

I was planning to cook lt/setup a bit longer but eventually
decided to merge it to 'master' as well after a short while.

	git checkout master
        git pull . __/setup-n-mv

I could have pulled lt/setup into master but then I would have
had to resolve the conflict between the two branches.  Since I
recorded the resolution earlier by making the merge, and pulled
that branch (which contained all of lt/setup already) ...
[ message continues ]

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.

--b.
-

[ message continues ]

(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

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."
		-- Kurt Vonnegut, Sirens from Titan
-

[ message continues ]

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.

--b.
-

[ message continues ]

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 <bfields@citi.umich.edu>
---
 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 ...
[ message continues ]

This has some useful material that fills gaps in the existing
documentation.  We need to think a little more about the intended
audience, and about how to fit it in with existing documentation.


Who's the audience for the above?  I can see that it's useful for
administrators, who may need help deciding how to install stuff, and for
developers, who need to know where the heck the code for "git-add" came
from.  But the case I'm most interested in is the user whose
distribution installs git for them, in which case I think the above
could be distilled down to:

	- "git-foo" and "git foo" can be used interchangeably.
	- Documentation for the command foo is available from any of
		- man git-foo
		- git help foo
		- git foo --help

Then the additional details above could be postponed to a later part of

I agree that that's helpful.  Though we should probably also be working

Obviously a more specific reference would be more useful here--if
there's nothing useful to point to among the existing documentation, we
should figure out how to fix that problem.


This is good; a comprehensive discussion of references will fill a gap
in the current documentation.


This has a lot more overlap with existing documentation.  The extra
detail is useful, but we need to decide what our audience and goal is
here, to decide exactly what niche we're trying to fill between the
brief stuff that's in the tutorial part I and the details in


Obviously there's a lot of overlap here with "man git-checkout".  What's
the goal here?  Maybe this should just be worked in to a revision of

It only checks whether the head of the branch to delete is reachable
from the *current* branch.  The man page could be clearer here.


Yep, we should definitely have a good long chapter just devoted to
history examination.  Most of it could be just cool examples, so it
would be fun.

Note some of this is done in the last half of cvs-migration.txt; we
should mine that section for whatever's useful and then ...
[ message continues ]

What ever happened to this document?  There was some talk of getting
this integrated into the git tree as Docmentation/tutorial-3.txt.
IMHO it would be really, really good to do this before 1.5.0, since I
think a lot of users would find it really useful.  Some of the text
may need to be moved to other locations, but it might go faster if we
get the base document into the tree first, and then we can submit
patches to move text around to integrate it into the other
documentation files.

I'm certainly willing to help out submitting patches to improve the
documentation, and I think this would be a big step towards helping
new users to git become much more quickly proficient.

						- Ted
-

[ message continues ]

Seconded.  Can I have the latest round?



-

[ message continues ]

> Seconded.  Can I have the latest round?

Uh... can it wait a day or two?  I'm leaving for a camping trip
tomorrow and won't have much keyboard access...

Sorry about that.
-

[ message continues ]

No worries.  Have fun.

-

[ message continues ]

Just to throw more fuel on the fire....

I have a draft attempt at a complete "git user's manual" at

	http://www.fieldses.org/~bfields/

The goals are:

	- Readable from beginning to end in order without having read
	  any other git documentation beforehand.
	- Helpful section names and cross-references, so it's not too
	  hard to skip around some if you need to.
	- Organized to allow it to grow much larger (unlike the
	  tutorials)

It's more liesurely than tutorial.txt, but tries to stay focused on
practical how-to stuff.  It adds a discussion of how to resolve merge
conflicts, and partial instructions on setting up and dealing with a
public repository.

I've lifted a little bit from "branching and merging" (e.g., some of the
discussion of history diagrams), and could probably steal more if that's
OK.  (Similarly anyone should of course feel free to reuse bits of this
if any parts seem more useful than the whole.)

There's a lot of detail on managing branches and using git-fetch, just
because those are essential even to people needing read-only access
(e.g., kernel testers).  I think those sections will be much shorter
once the new "git remote" command and the disconnected checkouts are
taken into account.

I do feel bad about adding yet another piece of documentation, but I we
need something that goes through all the basics in a logical order, and
I wasn't seeing how to grow the tutorials into that.

Opinions?

--b.
-

[ message continues ]

I was having the feeling that we need to start over the
documentation from a clean slate by first coming up with a
coherent presentation order and then filling sections in it,
instead of tweaking existing documents here and there.  The
existing documents were written in different development stages
of git, and each document tries to be more or less independent
from others in the area it wants to talk about, and reading all
of them in _any_ order is not the best way to learn git because
of duplication.  Also I suspect some information in older
documents, while being still valid and technically correct,
predates invention of a better/simpler alternative.

In other words, I think we have enough information in the
tutorial documents, but the problem is not the lack of
information -- the problem is the lack of organization.

I think this effort of yours is wonderful because it directly
tackles that problem.


-

[ message continues ]

OK, thanks for the vote of confidence....  My tentative organization
(which I'm totally open to argument about) is:

chapters 1 and 2: "Read-only" operations:

	clone, fetch, the commit DAG, etc.; material that could be
	useful to a linux kernel tester, for example.  This also
	includes lots of stuff about branch manipulation and fetching,
	just because that's necessary to keep a repo up to date and
	check out random commits.  Once we have "git remote" and
	disconnected checkouts most of this could be postponed till
	later.

Chapter 3: "Read-write" operations:

	Read-write stuff: creating commits (basic mention of index),
	handling merges, git-gc, ending with distributed stuff:
	importing and exporting patches, pull and push, etc.

Chapter 4 (unwritten): interactions with other VCS's

	cvs, subversion.  Also some of us use track projects with git
	even when all we've got is a sequence of release tarballs to
	track, and that might be worth documenting.

Chapter 5 (unwritten): rewriting history

	rebasing, cherry-picking, managing patch series, etc.

Chapter 6 (unwritten): git internals

	I intend to just do a wholesale import of either tutorial-2.txt,
	core-tutorial.txt, or the README, or some combination thereof,
	but can't decide which.

--b.
-

[ message continues ]

I would add a QuickStart Chapter before you start going into the
"read-only" oeperations.  It would show how to create a completely
empty repository, and add a few commits.  It would also demonstrate
how to clone an example repository (with a fixed set of contents,
stored at git://git.kernel.org/pub/scm/git/example and add a commit
using "git commit -a".

The basic idea is to show the user that git really isn't that hard,
*before* you start diving into a lot of details.  If you don't tell a
user how to make a commit until Chapter 3, he/she will assume it's

At least some discussions of branches needs to happen here; it's
really important to talk about different workflows, and how you use
branches as part of your read-write operations.  Some folks might or
might not use topic branches, but the concept of using temporary

You might want to consider putting these two chapters into appendices.

						- Ted
-

[ message continues ]

Yeah, I agree.  I just haven't been able to decide quite what to choose
for that purpose.  Some choices:

	- We could just pare down the tutorial a bit and drag it in as
	  chapter one.

	- I tried writing something modeled loosely on the hg quick
	  start.  It's a little out of date now, but that could be
	  fixed:

		http://www.fieldses.org/~bfields/git-quick-start.html

	- Or maybe a revised everyday.txt would do the job?


The basic nuts-and-bolts (how to create and delete branches, etc.)

.... Maybe it'd be fun to have a section called just "examples" at the
end of each chapter.  The sort of thing you're describing could fit in
well there.  I'd need some help collecting interesting examples.

--b.
-

[ message continues ]

I like this, although fetch should probably have "--force" instead of 
the "+branch" notation. --force stands out more and users are familiar 

I think the document is fine as it is, but could probably start off with 
a link to the tutorial, quickstart or a revised version of everyday.txt, 
stating that "here's something you might want to read if you prefer to 
experiment. If you think something goes wrong, come back here and find 

I found it quite sufficient. Perhaps it would be nice to include some 
more advanced examples, like octopus merges and things like that, 
although I feel such things could well live in an appendix to keep all 
the easy operations up front. Most people I know will most likely 
*never* use octopus merges. 90% of the merges we do here at work result 

Indeed. I for one like examples that tell me

# type this
# this will happen
# you can see what you just did with this, this, and this command
# this is because...

Not only is it good for learning the how and the why, but it also trains 
the fingers right from the start. Hopefully the UI is stabilized enough 
by now that we can reliably tell users how to accomplish a certain 
thing. UI changes must almost certainly be listed at whatever official 
site git has. As Junio has already pointed out, the members of the git 
mailing list are now in minority among the git users, so some other 
place has to hold the user-visible changes as well and the location of 
that site must probably be published along with the tools.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231
-

[ message continues ]

I started out writing it that way (for the reasons you give), then
changed it on the theory starting out with the "+" notation would make
it simpler explaining how to do the remote configuration.

Now that there's git-remote, and less need to manipulate the remote


OK.  This is a place where I'd really appreciate any contributions.

--b.
-

[ message continues ]

If what we're going to do is a "git user's manual", I'd recommend
keeping the 2-3 pages in the manual, and do it via a link to some
other document.  One of the issues with the git documentation is that
it's *too* branchy, and some the branches go off to some truly scary
low-level implementation detail.  If we are going to assume that isn't
going to change (and I am glad that the low-level details are
documented, and am not advocating that they be deleted), then keeping
a user-friendly QuickStart in the main document might not be a bad
decision.

						- Ted
-

[ message continues ]

Sounds reasonable.

I'll probably set this aside a few days, then do some more work on it
this weekend.  (Patches welcomed, though--source is in the master branch
of git://linux-nfs.org/~bfields/git.git.)

--b.
-

[ message continues ]

Is that the right URL?  That gets me to "Not Bruce's Webpage" and I
don't see an obvious link to git documentation...

						- Ted
-

[ message continues ]

Crap:

	http://www.fieldses.org/~bfields/git-user-manual.html

Sorry about that.--b.
-

[ message continues ]

J. Bruce Fields <bfields@fieldses.org> wrote:


A git repo? People want to rummage around in it...
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513
-

[ message continues ]

git://git.linux-nfs.org/~bfields/git.git

Note that I'm clueless about asciidoc, docbook, and friends, so I'm just
using whatever hack I could figure out to get the html looking OK.

And in general suggestions are welcomed.

--b.
-

[ message continues ]

Nice work.

My only 2 cents: the SVN book is really a good book, as it contains
both simple user and advanced hacker info. As it is in free licence,
perhaps it could be possible to "port" the book to Git. I saw that the
SVK book is such a port. But it's a DocBook document.
http://svnbook.red-bean.com/
-- 
Guilhem BONNEFILLE
-=- #UIN: 15146515 JID: guyou@im.apinc.org MSN: guilhem_bonnefille@hotmail.com
-=- mailto:guilhem.bonnefille@gmail.com
-=- http://nathguil.free.fr/
-

[ message continues ]

Thanks, yes, that does look very polished.

If there's any part you'd be particularly interested in seeing "ported",
I'd be happy to help incorporate your work.

--b.
-

[ message continues ]