login
Search
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 ...
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.
-
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.
-
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" -
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 ...
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; -
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).
...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 ...
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 -
Or.. find a way to merge cogito back to git :-) /me runs into a nearest bush. -- Duy -
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 -
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*',/((..)*)$/) -
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 -
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 ...
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?) -
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
-
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 ...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 ...
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. -
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. -
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 -
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) ...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. -
(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 -
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. -
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 ...
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 ...
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 -
Seconded. Can I have the latest round? -
> 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. -
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. -
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. -
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. -
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 -
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. -
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 -
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. -
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 -
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. -
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 -
Crap: http://www.fieldses.org/~bfields/git-user-manual.html Sorry about that.--b. -
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 -
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. -
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/ -
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. -
