-A short git tutorial
-====================
-v0.99.5, Aug 2005
-
-Introduction
-------------
-
-This is trying to be a short tutorial on setting up and using a git
-repository, mainly because being hands-on and using explicit examples is
-often the best way of explaining what is going on.
-
-In normal life, most people wouldn't use the "core" git programs
-directly, but rather script around them to make them more palatable.
-Understanding the core git stuff may help some people get those scripts
-done, though, and it may also be instructive in helping people
-understand what it is that the higher-level helper scripts are actually
-doing.
-
-The core git is often called "plumbing", with the prettier user
-interfaces on top of it called "porcelain". You may not want to use the
-plumbing directly very often, but it can be good to know what the
-plumbing does for when the porcelain isn't flushing...
-
-
-Creating a git repository
--------------------------
-
-Creating a new git repository couldn't be easier: all git repositories start
-out empty, and the only thing you need to do is find yourself a
-subdirectory that you want to use as a working tree - either an empty
-one for a totally new project, or an existing working tree that you want
-to import into git.
-
-For our first example, we're going to start a totally new repository from
-scratch, with no pre-existing files, and we'll call it "git-tutorial".
-To start up, create a subdirectory for it, change into that
-subdirectory, and initialize the git infrastructure with "git-init-db":
-
- mkdir git-tutorial
- cd git-tutorial
- git-init-db
-
-to which git will reply
-
- defaulting to local storage area
-
-which is just git's way of saying that you haven't been doing anything
-strange, and that it will have created a local .git directory setup for
-your new project. You will now have a ".git" directory, and you can
-inspect that with "ls". For your new empty project, ls should show you
-three entries, among other things:
-
- - a symlink called HEAD, pointing to "refs/heads/master"
-
- Don't worry about the fact that the file that the HEAD link points to
- doesn't even exist yet - you haven't created the commit that will
- start your HEAD development branch yet.
-
- - a subdirectory called "objects", which will contain all the
- objects of your project. You should never have any real reason to
- look at the objects directly, but you might want to know that these
- objects are what contains all the real _data_ in your repository.
-
- - a subdirectory called "refs", which contains references to objects.
-
- In particular, the "refs" subdirectory will contain two other
- subdirectories, named "heads" and "tags" respectively. They do
- exactly what their names imply: they contain references to any number
- of different "heads" of development (aka "branches"), and to any
- "tags" that you have created to name specific versions in your
- repository.
-
- One note: the special "master" head is the default branch, which is
- why the .git/HEAD file was created as a symlink to it even if it
- doesn't yet exist. Basically, the HEAD link is supposed to always
- point to the branch you are working on right now, and you always
- start out expecting to work on the "master" branch.
-
- However, this is only a convention, and you can name your branches
- anything you want, and don't have to ever even _have_ a "master"
- branch. A number of the git tools will assume that .git/HEAD is
- valid, though.
-
- [ Implementation note: an "object" is identified by its 160-bit SHA1
- hash, aka "name", and a reference to an object is always the 40-byte
- hex representation of that SHA1 name. The files in the "refs"
- subdirectory are expected to contain these hex references (usually
- with a final '\n' at the end), and you should thus expect to see a
- number of 41-byte files containing these references in this refs
- subdirectories when you actually start populating your tree ]
-
-You have now created your first git repository. Of course, since it's
-empty, that's not very useful, so let's start populating it with data.
-
-
-Populating a git repository
----------------------------
-
-We'll keep this simple and stupid, so we'll start off with populating a
-few trivial files just to get a feel for it.
-
-Start off with just creating any random files that you want to maintain
-in your git repository. We'll start off with a few bad examples, just to
-get a feel for how this works:
-
- echo "Hello World" >hello
- echo "Silly example" >example
-
-you have now created two files in your working tree (aka "working directory"), but to
-actually check in your hard work, you will have to go through two steps:
-
- - fill in the "index" file (aka "cache") with the information about your
- working tree state.
-
- - commit that index file as an object.
-
-The first step is trivial: when you want to tell git about any changes
-to your working tree, you use the "git-update-cache" program. That
-program normally just takes a list of filenames you want to update, but
-to avoid trivial mistakes, it refuses to add new entries to the cache
-(or remove existing ones) unless you explicitly tell it that you're
-adding a new entry with the "--add" flag (or removing an entry with the
-"--remove") flag.
-
-So to populate the index with the two files you just created, you can do
-
- git-update-cache --add hello example
-
-and you have now told git to track those two files.
-
-In fact, as you did that, if you now look into your object directory,
-you'll notice that git will have added two new objects to the object
-database. If you did exactly the steps above, you should now be able to do
-
- ls .git/objects/??/*
-
-and see two files:
-
- .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
- .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
-
-which correspond with the objects with names of 557db... and f24c7..
-respectively.
-
-If you want to, you can use "git-cat-file" to look at those objects, but
-you'll have to use the object name, not the filename of the object:
-
- git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
-
-where the "-t" tells git-cat-file to tell you what the "type" of the
-object is. Git will tell you that you have a "blob" object (ie just a
-regular file), and you can see the contents with
-
- git-cat-file "blob" 557db03
-
-which will print out "Hello World". The object 557db03 is nothing
-more than the contents of your file "hello".
-
-[ Digression: don't confuse that object with the file "hello" itself. The
- object is literally just those specific _contents_ of the file, and
- however much you later change the contents in file "hello", the object we
- just looked at will never change. Objects are immutable. ]
-
-[ Digression #2: the second example demonstrates that you can
- abbreviate the object name to only the first several
- hexadecimal digits in most places. ]
-
-Anyway, as we mentioned previously, you normally never actually take a
-look at the objects themselves, and typing long 40-character hex
-names is not something you'd normally want to do. The above digression
-was just to show that "git-update-cache" did something magical, and
-actually saved away the contents of your files into the git object
-database.
-
-Updating the cache did something else too: it created a ".git/index"
-file. This is the index that describes your current working tree, and
-something you should be very aware of. Again, you normally never worry
-about the index file itself, but you should be aware of the fact that
-you have not actually really "checked in" your files into git so far,
-you've only _told_ git about them.
-
-However, since git knows about them, you can now start using some of the
-most basic git commands to manipulate the files or look at their status.
+A tutorial introduction to git
+==============================
-In particular, let's not even check in the two files into git yet, we'll
-start off by adding another line to "hello" first:
+This tutorial explains how to import a new project into git, make
+changes to it, and share changes with other developers.
- echo "It's a new day for git" >>hello
+First, note that you can get documentation for a command such as "git
+diff" with:
-and you can now, since you told git about the previous state of "hello", ask
-git what has changed in the tree compared to your old index, using the
-"git-diff-files" command:
-
- git-diff-files
-
-Oops. That wasn't very readable. It just spit out its own internal
-version of a "diff", but that internal version really just tells you
-that it has noticed that "hello" has been modified, and that the old object
-contents it had have been replaced with something else.
-
-To make it readable, we can tell git-diff-files to output the
-differences as a patch, using the "-p" flag:
-
- git-diff-files -p
-
-which will spit out
-
- diff --git a/hello b/hello
- --- a/hello
- +++ b/hello
- @@ -1 +1,2 @@
- Hello World
- +It's a new day for git
-
-ie the diff of the change we caused by adding another line to "hello".
-
-In other words, git-diff-files always shows us the difference between
-what is recorded in the index, and what is currently in the working
-tree. That's very useful.
-
-A common shorthand for "git-diff-files -p" is to just write
-
- git diff
-
-which will do the same thing.
-
-
-Committing git state
---------------------
-
-Now, we want to go to the next stage in git, which is to take the files
-that git knows about in the index, and commit them as a real tree. We do
-that in two phases: creating a "tree" object, and committing that "tree"
-object as a "commit" object together with an explanation of what the
-tree was all about, along with information of how we came to that state.
-
-Creating a tree object is trivial, and is done with "git-write-tree".
-There are no options or other input: git-write-tree will take the
-current index state, and write an object that describes that whole
-index. In other words, we're now tying together all the different
-filenames with their contents (and their permissions), and we're
-creating the equivalent of a git "directory" object:
-
- git-write-tree
-
-and this will just output the name of the resulting tree, in this case
-(if you have done exactly as I've described) it should be
-
- 8988da15d077d4829fc51d8544c097def6644dbb
-
-which is another incomprehensible object name. Again, if you want to,
-you can use "git-cat-file -t 8988d.." to see that this time the object
-is not a "blob" object, but a "tree" object (you can also use
-git-cat-file to actually output the raw object contents, but you'll see
-mainly a binary mess, so that's less interesting).
-
-However - normally you'd never use "git-write-tree" on its own, because
-normally you always commit a tree into a commit object using the
-"git-commit-tree" command. In fact, it's easier to not actually use
-git-write-tree on its own at all, but to just pass its result in as an
-argument to "git-commit-tree".
-
-"git-commit-tree" normally takes several arguments - it wants to know
-what the _parent_ of a commit was, but since this is the first commit
-ever in this new repository, and it has no parents, we only need to pass in
-the object name of the tree. However, git-commit-tree also wants to get a commit message
-on its standard input, and it will write out the resulting object name for the
-commit to its standard output.
+------------------------------------------------
+$ man git-diff
+------------------------------------------------
-And this is where we start using the .git/HEAD file. The HEAD file is
-supposed to contain the reference to the top-of-tree, and since that's
-exactly what git-commit-tree spits out, we can do this all with a simple
-shell pipeline:
+Importing a new project
+-----------------------
- echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD
+Assume you have a tarball project.tar.gz with your initial work. You
+can place it under git revision control as follows.
-which will say:
+------------------------------------------------
+$ tar xzf project.tar.gz
+$ cd project
+$ git init-db
+------------------------------------------------
- Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
+Git will reply
-just to warn you about the fact that it created a totally new commit
-that is not related to anything else. Normally you do this only _once_
-for a project ever, and all later commits will be parented on top of an
-earlier commit, and you'll never see this "Committing initial tree"
-message ever again.
+------------------------------------------------
+defaulting to local storage area
+------------------------------------------------
-Again, normally you'd never actually do this by hand. There is a
-helpful script called "git commit" that will do all of this for you. So
-you could have just written
+You've now initialized the working directory--you may notice a new
+directory created, named ".git". Tell git that you want it to track
+every file under the current directory with
- git commit
+------------------------------------------------
+$ git add .
+------------------------------------------------
-instead, and it would have done the above magic scripting for you.
+Finally,
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
-Making a change
----------------
+will prompt you for a commit message, then record the current state
+of all the files to the repository.
-Remember how we did the "git-update-cache" on file "hello" and then we
-changed "hello" afterward, and could compare the new state of "hello" with the
-state we saved in the index file?
+Try modifying some files, then run
-Further, remember how I said that "git-write-tree" writes the contents
-of the _index_ file to the tree, and thus what we just committed was in
-fact the _original_ contents of the file "hello", not the new ones. We did
-that on purpose, to show the difference between the index state, and the
-state in the working tree, and how they don't have to match, even
-when we commit things.
+------------------------------------------------
+$ git diff
+------------------------------------------------
-As before, if we do "git-diff-files -p" in our git-tutorial project,
-we'll still see the same difference we saw last time: the index file
-hasn't changed by the act of committing anything. However, now that we
-have committed something, we can also learn to use a new command:
-"git-diff-cache".
+to review your changes. When you're done,
-Unlike "git-diff-files", which showed the difference between the index
-file and the working tree, "git-diff-cache" shows the differences
-between a committed _tree_ and either the index file or the working
-tree. In other words, git-diff-cache wants a tree to be diffed
-against, and before we did the commit, we couldn't do that, because we
-didn't have anything to diff against.
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
-But now we can do
+will again prompt your for a message describing the change, and then
+record the new versions of the modified files.
- git-diff-cache -p HEAD
-
-(where "-p" has the same meaning as it did in git-diff-files), and it
-will show us the same difference, but for a totally different reason.
-Now we're comparing the working tree not against the index file,
-but against the tree we just wrote. It just so happens that those two
-are obviously the same, so we get the same result.
-
-Again, because this is a common operation, you can also just shorthand
-it with
-
- git diff HEAD
-
-which ends up doing the above for you.
-
-In other words, "git-diff-cache" normally compares a tree against the
-working tree, but when given the "--cached" flag, it is told to
-instead compare against just the index cache contents, and ignore the
-current working tree state entirely. Since we just wrote the index
-file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus return
-an empty set of differences, and that's exactly what it does.
-
-[ Digression: "git-diff-cache" really always uses the index for its
- comparisons, and saying that it compares a tree against the working
- tree is thus not strictly accurate. In particular, the list of
- files to compare (the "meta-data") _always_ comes from the index file,
- regardless of whether the --cached flag is used or not. The --cached
- flag really only determines whether the file _contents_ to be compared
- come from the working tree or not.
-
- This is not hard to understand, as soon as you realize that git simply
- never knows (or cares) about files that it is not told about
- explicitly. Git will never go _looking_ for files to compare, it
- expects you to tell it what the files are, and that's what the index
- is there for. ]
-
-However, our next step is to commit the _change_ we did, and again, to
-understand what's going on, keep in mind the difference between "working
-tree contents", "index file" and "committed tree". We have changes
-in the working tree that we want to commit, and we always have to
-work through the index file, so the first thing we need to do is to
-update the index cache:
+A note on commit messages: Though not required, it's a good idea to
+begin the commit message with a single short (less than 50 character)
+line summarizing the change, followed by a blank line and then a more
+thorough description. Tools that turn commits into email, for
+example, use the first line on the Subject line and the rest of the
+commit in the body.
- git-update-cache hello
+To add a new file, first create the file, then
-(note how we didn't need the "--add" flag this time, since git knew
-about the file already).
+------------------------------------------------
+$ git add path/to/new/file
+------------------------------------------------
-Note what happens to the different git-diff-xxx versions here. After
-we've updated "hello" in the index, "git-diff-files -p" now shows no
-differences, but "git-diff-cache -p HEAD" still _does_ show that the
-current state is different from the state we committed. In fact, now
-"git-diff-cache" shows the same difference whether we use the "--cached"
-flag or not, since now the index is coherent with the working tree.
-
-Now, since we've updated "hello" in the index, we can commit the new
-version. We could do it by writing the tree by hand again, and
-committing the tree (this time we'd have to use the "-p HEAD" flag to
-tell commit that the HEAD was the _parent_ of the new commit, and that
-this wasn't an initial commit any more), but you've done that once
-already, so let's just use the helpful script this time:
+then commit as usual. No special command is required when removing a
+file; just remove it, then commit.
- git commit
-
-which starts an editor for you to write the commit message and tells you
-a bit about what you have done.
-
-Write whatever message you want, and all the lines that start with '#'
-will be pruned out, and the rest will be used as the commit message for
-the change. If you decide you don't want to commit anything after all at
-this point (you can continue to edit things and update the cache), you
-can just leave an empty message. Otherwise git-commit-script will commit
-the change for you.
-
-You've now made your first real git commit. And if you're interested in
-looking at what git-commit-script really does, feel free to investigate:
-it's a few very simple shell scripts to generate the helpful (?) commit
-message headers, and a few one-liners that actually do the commit itself.
-
-
-Checking it out
----------------
-
-While creating changes is useful, it's even more useful if you can tell
-later what changed. The most useful command for this is another of the
-"diff" family, namely "git-diff-tree".
-
-git-diff-tree can be given two arbitrary trees, and it will tell you the
-differences between them. Perhaps even more commonly, though, you can
-give it just a single commit object, and it will figure out the parent
-of that commit itself, and show the difference directly. Thus, to get
-the same diff that we've already seen several times, we can now do
-
- git-diff-tree -p HEAD
-
-(again, "-p" means to show the difference as a human-readable patch),
-and it will show what the last commit (in HEAD) actually changed.
+At any point you can view the history of your changes using
-More interestingly, you can also give git-diff-tree the "-v" flag, which
-tells it to also show the commit message and author and date of the
-commit, and you can tell it to show a whole series of diffs.
-Alternatively, you can tell it to be "silent", and not show the diffs at
-all, but just show the actual commit message.
-
-In fact, together with the "git-rev-list" program (which generates a
-list of revisions), git-diff-tree ends up being a veritable fount of
-changes. A trivial (but very useful) script called "git-whatchanged" is
-included with git which does exactly this, and shows a log of recent
-activities.
-
-To see the whole history of our pitiful little git-tutorial project, you
-can do
-
- git log
-
-which shows just the log messages, or if we want to see the log together
-with the associated patches use the more complex (and much more
-powerful)
-
- git-whatchanged -p --root
-
-and you will see exactly what has changed in the repository over its
-short history.
-
-[ Side note: the "--root" flag is a flag to git-diff-tree to tell it to
- show the initial aka "root" commit too. Normally you'd probably not
- want to see the initial import diff, but since the tutorial project
- was started from scratch and is so small, we use it to make the result
- a bit more interesting. ]
+------------------------------------------------
+$ git whatchanged
+------------------------------------------------
-With that, you should now be having some inkling of what git does, and
-can explore on your own.
-
-[ Side note: most likely, you are not directly using the core
- git Plumbing commands, but using Porcelain like Cogito on top
- of it. Cogito works a bit differently and you usually do not
- have to run "git-update-cache" yourself for changed files (you
- do tell underlying git about additions and removals via
- "cg-add" and "cg-rm" commands). Just before you make a commit
- with "cg-commit", Cogito figures out which files you modified,
- and runs "git-update-cache" on them for you. ]
+If you also want to see complete diffs at each step, use
+------------------------------------------------
+$ git whatchanged -p
+------------------------------------------------
-Tagging a version
+Managing branches
-----------------
-In git, there are two kinds of tags, a "light" one, and an "annotated tag".
-
-A "light" tag is technically nothing more than a branch, except we put
-it in the ".git/refs/tags/" subdirectory instead of calling it a "head".
-So the simplest form of tag involves nothing more than
-
- git tag my-first-tag
-
-which just writes the current HEAD into the .git/refs/tags/my-first-tag
-file, after which point you can then use this symbolic name for that
-particular state. You can, for example, do
-
- git diff my-first-tag
-
-to diff your current state against that tag (which at this point will
-obviously be an empty diff, but if you continue to develop and commit
-stuff, you can use your tag as an "anchor-point" to see what has changed
-since you tagged it.
-
-An "annotated tag" is actually a real git object, and contains not only a
-pointer to the state you want to tag, but also a small tag name and
-message, along with optionally a PGP signature that says that yes, you really did
-that tag. You create these signed tags with either the "-a" or "-s" flag to "git tag":
-
- git tag -s <tagname>
-
-which will sign the current HEAD (but you can also give it another
-argument that specifies the thing to tag, ie you could have tagged the
-current "mybranch" point by using "git tag <tagname> mybranch").
-
-You normally only do signed tags for major releases or things
-like that, while the light-weight tags are useful for any marking you
-want to do - any time you decide that you want to remember a certain
-point, just create a private tag for it, and you have a nice symbolic
-name for the state at that point.
-
-
-Copying repositories
---------------------
-
-Git repositories are normally totally self-sufficient, and it's worth noting
-that unlike CVS, for example, there is no separate notion of
-"repository" and "working tree". A git repository normally _is_ the
-working tree, with the local git information hidden in the ".git"
-subdirectory. There is nothing else. What you see is what you got.
-
-[ Side note: you can tell git to split the git internal information from
- the directory that it tracks, but we'll ignore that for now: it's not
- how normal projects work, and it's really only meant for special uses.
- So the mental model of "the git information is always tied directly to
- the working tree that it describes" may not be technically 100%
- accurate, but it's a good model for all normal use ]
-
-This has two implications:
-
- - if you grow bored with the tutorial repository you created (or you've
- made a mistake and want to start all over), you can just do simple
-
- rm -rf git-tutorial
-
- and it will be gone. There's no external repository, and there's no
- history outside the project you created.
-
- - if you want to move or duplicate a git repository, you can do so. There
- is "git clone" command, but if all you want to do is just to
- create a copy of your repository (with all the full history that
- went along with it), you can do so with a regular
- "cp -a git-tutorial new-git-tutorial".
-
- Note that when you've moved or copied a git repository, your git index
- file (which caches various information, notably some of the "stat"
- information for the files involved) will likely need to be refreshed.
- So after you do a "cp -a" to create a new copy, you'll want to do
-
- git-update-cache --refresh
-
- in the new repository to make sure that the index file is up-to-date.
-
-Note that the second point is true even across machines. You can
-duplicate a remote git repository with _any_ regular copy mechanism, be it
-"scp", "rsync" or "wget".
-
-When copying a remote repository, you'll want to at a minimum update the
-index cache when you do this, and especially with other peoples'
-repositories you often want to make sure that the index cache is in some
-known state (you don't know _what_ they've done and not yet checked in),
-so usually you'll precede the "git-update-cache" with a
-
- git-read-tree --reset HEAD
- git-update-cache --refresh
-
-which will force a total index re-build from the tree pointed to by HEAD.
-It resets the index contents to HEAD, and then the git-update-cache
-makes sure to match up all index entries with the checked-out files.
-If the original repository had uncommitted changes in its
-working tree, "git-update-cache --refresh" notices them and
-tells you they need to be updated.
-
-The above can also be written as simply
-
- git reset
-
-and in fact a lot of the common git command combinations can be scripted
-with the "git xyz" interfaces, and you can learn things by just looking
-at what the git-*-script scripts do ("git reset" is the above two lines
-implemented in "git-reset-script", but some things like "git status" and
-"git commit" are slightly more complex scripts around the basic git
-commands).
-
-Many (most?) public remote repositories will not contain any of
-the checked out files or even an index file, and will _only_ contain the
-actual core git files. Such a repository usually doesn't even have the
-".git" subdirectory, but has all the git files directly in the
-repository.
-
-To create your own local live copy of such a "raw" git repository, you'd
-first create your own subdirectory for the project, and then copy the
-raw repository contents into the ".git" directory. For example, to
-create your own copy of the git repository, you'd do the following
-
- mkdir my-git
- cd my-git
- rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
-
-followed by
-
- git-read-tree HEAD
-
-to populate the index. However, now you have populated the index, and
-you have all the git internal files, but you will notice that you don't
-actually have any of the working tree files to work on. To get
-those, you'd check them out with
-
- git-checkout-cache -u -a
-
-where the "-u" flag means that you want the checkout to keep the index
-up-to-date (so that you don't have to refresh it afterward), and the
-"-a" flag means "check out all files" (if you have a stale copy or an
-older version of a checked out tree you may also need to add the "-f"
-flag first, to tell git-checkout-cache to _force_ overwriting of any old
-files).
-
-Again, this can all be simplified with
-
- git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
- cd my-git
- git checkout
-
-which will end up doing all of the above for you.
-
-You have now successfully copied somebody else's (mine) remote
-repository, and checked it out.
-
-
-Creating a new branch
----------------------
-
-Branches in git are really nothing more than pointers into the git
-object database from within the ".git/refs/" subdirectory, and as we
-already discussed, the HEAD branch is nothing but a symlink to one of
-these object pointers.
-
-You can at any time create a new branch by just picking an arbitrary
-point in the project history, and just writing the SHA1 name of that
-object into a file under .git/refs/heads/. You can use any filename you
-want (and indeed, subdirectories), but the convention is that the
-"normal" branch is called "master". That's just a convention, though,
-and nothing enforces it.
-
-To show that as an example, let's go back to the git-tutorial repository we
-used earlier, and create a branch in it. You do that by simply just
-saying that you want to check out a new branch:
-
- git checkout -b mybranch
-
-will create a new branch based at the current HEAD position, and switch
-to it.
-
-[ Side note: if you make the decision to start your new branch at some
- other point in the history than the current HEAD, you can do so by
- just telling "git checkout" what the base of the checkout would be.
- In other words, if you have an earlier tag or branch, you'd just do
-
- git checkout -b mybranch earlier-commit
-
- and it would create the new branch "mybranch" at the earlier commit,
- and check out the state at that time. ]
-
-You can always just jump back to your original "master" branch by doing
-
- git checkout master
-
-(or any other branch-name, for that matter) and if you forget which
-branch you happen to be on, a simple
-
- ls -l .git/HEAD
-
-will tell you where it's pointing. To get the list of branches
-you have, you can say
-
- git branch
-
-which is nothing more than a simple script around "ls .git/refs/heads".
-
-Sometimes you may wish to create a new branch _without_ actually
-checking it out and switching to it. If so, just use the command
-
- git branch <branchname> [startingpoint]
-
-which will simply _create_ the branch, but will not do anything further.
-You can then later - once you decide that you want to actually develop
-on that branch - switch to that branch with a regular "git checkout"
-with the branchname as the argument.
-
-
-Merging two branches
---------------------
-
-One of the ideas of having a branch is that you do some (possibly
-experimental) work in it, and eventually merge it back to the main
-branch. So assuming you created the above "mybranch" that started out
-being the same as the original "master" branch, let's make sure we're in
-that branch, and do some work there.
-
- git checkout mybranch
- echo "Work, work, work" >>hello
- git commit -m 'Some work.' hello
-
-Here, we just added another line to "hello", and we used a shorthand for
-both going a "git-update-cache hello" and "git commit" by just giving the
-filename directly to "git commit". The '-m' flag is to give the
-commit log message from the command line.
-
-Now, to make it a bit more interesting, let's assume that somebody else
-does some work in the original branch, and simulate that by going back
-to the master branch, and editing the same file differently there:
-
- git checkout master
-
-Here, take a moment to look at the contents of "hello", and notice how they
-don't contain the work we just did in "mybranch" - because that work
-hasn't happened in the "master" branch at all. Then do
-
- echo "Play, play, play" >>hello
- echo "Lots of fun" >>example
- git commit -m 'Some fun.' hello example
-
-since the master branch is obviously in a much better mood.
-
-Now, you've got two branches, and you decide that you want to merge the
-work done. Before we do that, let's introduce a cool graphical tool that
-helps you view what's going on:
-
- gitk --all
-
-will show you graphically both of your branches (that's what the "--all"
-means: normally it will just show you your current HEAD) and their
-histories. You can also see exactly how they came to be from a common
-source.
-
-Anyway, let's exit gitk (^Q or the File menu), and decide that we want
-to merge the work we did on the "mybranch" branch into the "master"
-branch (which is currently our HEAD too). To do that, there's a nice
-script called "git resolve", which wants to know which branches you want
-to resolve and what the merge is all about:
-
- git resolve HEAD mybranch "Merge work in mybranch"
-
-where the third argument is going to be used as the commit message if
-the merge can be resolved automatically.
-
-Now, in this case we've intentionally created a situation where the
-merge will need to be fixed up by hand, though, so git will do as much
-of it as it can automatically (which in this case is just merge the "example"
-file, which had no differences in the "mybranch" branch), and say:
-
- Simple merge failed, trying Automatic merge
- Auto-merging hello.
- merge: warning: conflicts during merge
- ERROR: Merge conflict in hello.
- fatal: merge program failed
- Automatic merge failed, fix up by hand
-
-which is way too verbose, but it basically tells you that it failed the
-really trivial merge ("Simple merge") and did an "Automatic merge"
-instead, but that too failed due to conflicts in "hello".
-
-Not to worry. It left the (trivial) conflict in "hello" in the same form you
-should already be well used to if you've ever used CVS, so let's just
-open "hello" in our editor (whatever that may be), and fix it up somehow.
-I'd suggest just making it so that "hello" contains all four lines:
-
- Hello World
- It's a new day for git
- Play, play, play
- Work, work, work
-
-and once you're happy with your manual merge, just do a
-
- git commit hello
-
-which will very loudly warn you that you're now committing a merge
-(which is correct, so never mind), and you can write a small merge
-message about your adventures in git-merge-land.
-
-After you're done, start up "gitk --all" to see graphically what the
-history looks like. Notice that "mybranch" still exists, and you can
-switch to it, and continue to work with it if you want to. The
-"mybranch" branch will not contain the merge, but next time you merge it
-from the "master" branch, git will know how you merged it, so you'll not
-have to do _that_ merge again.
-
-Another useful tool, especially if you do not work in X-Window
-environment all the time, is "git show-branch".
+A single git repository can maintain multiple branches of
+development. To create a new branch named "experimental", use
------------------------------------------------
-$ git show-branch master mybranch
-* [master] Merged "mybranch" changes.
- ! [mybranch] Some work.
---
-+ [master] Merged "mybranch" changes.
-+ [master~1] Some fun.
-++ [mybranch] Some work.
+$ git branch experimental
------------------------------------------------
-The first two lines indicate that it is showing the two branches
-and the first line of the commit log message from their
-top-of-the-tree commits, you are currently on "master" branch
-(notice the asterisk "*" character), and the first column for
-the later output lines is used to show commits contained in the
-"master" branch, and the second column for the "mybranch"
-branch. Three commits are shown along with their log messages.
-All of them have plus '+' characters in the first column, which
-means they are now part of the "master" branch. Only the "Some
-work" commit has the plus '+' character in the second column,
-because "mybranch" has not been merged to incorporate these
-commits from the master branch.
-
-Now, let's pretend you are the one who did all the work in
-mybranch, and the fruit of your hard work has finally been merged
-to the master branch. Let's go back to "mybranch", and run
-resolve to get the "upstream changes" back to your branch.
-
- git checkout mybranch
- git resolve HEAD master "Merge upstream changes."
-
-This outputs something like this (the actual commit object names
-would be different)
-
- Updating from ae3a2da... to a80b4aa....
- example | 1 +
- hello | 1 +
- 2 files changed, 2 insertions(+), 0 deletions(-)
-
-Because your branch did not contain anything more than what are
-already merged into the master branch, the resolve operation did
-not actually do a merge. Instead, it just updated the top of
-the tree of your branch to that of the "master" branch. This is
-often called "fast forward" merge.
-
-You can run "gitk --all" again to see how the commit ancestry
-looks like, or run "show-branch", which tells you this.
+If you now run
------------------------------------------------
-$ git show-branch master mybranch
-! [master] Merged "mybranch" changes.
- * [mybranch] Merged "mybranch" changes.
---
-++ [master] Merged "mybranch" changes.
+$ git branch
------------------------------------------------
-
-Merging external work
----------------------
-
-It's usually much more common that you merge with somebody else than
-merging with your own branches, so it's worth pointing out that git
-makes that very easy too, and in fact, it's not that different from
-doing a "git resolve". In fact, a remote merge ends up being nothing
-more than "fetch the work from a remote repository into a temporary tag"
-followed by a "git resolve".
-
-It's such a common thing to do that it's called "git pull", and you can
-simply do
-
- git pull <remote-repository>
-
-and optionally give a branch-name for the remote end as a second
-argument.
-
-The "remote" repository can even be on the same machine. One of
-the following notations can be used to name the repository to
-pull from:
-
- Rsync URL
- rsync://remote.machine/path/to/repo.git/
-
- HTTP(s) URL
- http://remote.machine/path/to/repo.git/
-
- GIT URL
- git://remote.machine/path/to/repo.git/
-
- SSH URL
- remote.machine:/path/to/repo.git/
-
- Local directory
- /path/to/repo.git/
-
-[ Digression: you could do without using any branches at all, by
- keeping as many local repositories as you would like to have
- branches, and merging between them with "git pull", just like
- you merge between branches. The advantage of this approach is
- that it lets you keep set of files for each "branch" checked
- out and you may find it easier to switch back and forth if you
- juggle multiple lines of development simultaneously. Of
- course, you will pay the price of more disk usage to hold
- multiple working trees, but disk space is cheap these days. ]
-
-[ Digression #2: you could even pull from your own repository by
- giving '.' as <remote-repository> parameter to "git pull". ]
-
-It is likely that you will be pulling from the same remote
-repository from time to time. As a short hand, you can store
-the remote repository URL in a file under .git/remotes/
-directory, like this:
+you'll get a list of all existing branches:
------------------------------------------------
-mkdir -p .git/remotes/
-cat >.git/remotes/linus <<\EOF
-URL: http://www.kernel.org/pub/scm/git/git.git/
-EOF
+ experimental
+* master
------------------------------------------------
-and use the filename to "git pull" instead of the full URL.
-The URL specified in such file can even be a prefix
-of a full URL, like this:
+The "experimental" branch is the one you just created, and the
+"master" branch is a default branch that was created for you
+automatically. The asterisk marks the branch you are currently on;
+type
------------------------------------------------
-cat >.git/remotes/jgarzik <<\EOF
-URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
-EOF
+$ git checkout experimental
------------------------------------------------
+to switch to the experimental branch. Now edit a file, commit the
+change, and switch back to the master branch:
-Examples.
-
- (1) git pull linus
- (2) git pull linus tag v0.99.1
- (3) git pull jgarzik/netdev-2.6.git/ e100
-
-the above are equivalent to:
-
- (1) git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD
- (2) git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1
- (3) git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100
-
-
-Publishing your work
---------------------
-
-So we can use somebody else's work from a remote repository; but
-how can _you_ prepare a repository to let other people pull from
-it?
-
-Your do your real work in your working tree that has your
-primary repository hanging under it as its ".git" subdirectory.
-You _could_ make that repository accessible remotely and ask
-people to pull from it, but in practice that is not the way
-things are usually done. A recommended way is to have a public
-repository, make it reachable by other people, and when the
-changes you made in your primary working tree are in good shape,
-update the public repository from it. This is often called
-"pushing".
-
-[ Side note: this public repository could further be mirrored,
- and that is how kernel.org git repositories are done. ]
+------------------------------------------------
+(edit file)
+$ git commit -a
+$ git checkout master
+------------------------------------------------
-Publishing the changes from your local (private) repository to
-your remote (public) repository requires a write privilege on
-the remote machine. You need to have an SSH account there to
-run a single command, "git-receive-pack".
+Check that the change you made is no longer visible, since it was
+made on the experimental branch and you're back on the master branch.
-First, you need to create an empty repository on the remote
-machine that will house your public repository. This empty
-repository will be populated and be kept up-to-date by pushing
-into it later. Obviously, this repository creation needs to be
-done only once.
+You can make a different change on the master branch:
-[ Digression: "git push" uses a pair of programs,
- "git-send-pack" on your local machine, and "git-receive-pack"
- on the remote machine. The communication between the two over
- the network internally uses an SSH connection. ]
+------------------------------------------------
+(edit file)
+$ git commit -a
+------------------------------------------------
-Your private repository's GIT directory is usually .git, but
-your public repository is often named after the project name,
-i.e. "<project>.git". Let's create such a public repository for
-project "my-git". After logging into the remote machine, create
-an empty directory:
+at this point the two branches have diverged, with different changes
+made in each. To merge the changes made in the two branches, run
- mkdir my-git.git
+------------------------------------------------
+$ git pull . experimental
+------------------------------------------------
-Then, make that directory into a GIT repository by running
-git-init-db, but this time, since its name is not the usual
-".git", we do things slightly differently:
+If the changes don't conflict, you're done. If there are conflicts,
+markers will be left in the problematic files showing the conflict;
- GIT_DIR=my-git.git git-init-db
+------------------------------------------------
+$ git diff
+------------------------------------------------
-Make sure this directory is available for others you want your
-changes to be pulled by via the transport of your choice. Also
-you need to make sure that you have the "git-receive-pack"
-program on the $PATH.
+will show this. Once you've edited the files to resolve the
+conflicts,
-[ Side note: many installations of sshd do not invoke your shell
- as the login shell when you directly run programs; what this
- means is that if your login shell is bash, only .bashrc is
- read and not .bash_profile. As a workaround, make sure
- .bashrc sets up $PATH so that you can run 'git-receive-pack'
- program. ]
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
-Your "public repository" is now ready to accept your changes.
-Come back to the machine you have your private repository. From
-there, run this command:
+will commit the result of the merge. Finally,
- git push <public-host>:/path/to/my-git.git master
+------------------------------------------------
+$ gitk
+------------------------------------------------
-This synchronizes your public repository to match the named
-branch head (i.e. "master" in this case) and objects reachable
-from them in your current repository.
+will show a nice graphical representation of the resulting history.
-As a real example, this is how I update my public git
-repository. Kernel.org mirror network takes care of the
-propagation to other publicly visible machines:
+If you develop on a branch crazy-idea, then regret it, you can always
+delete the branch with
- git push master.kernel.org:/pub/scm/git/git.git/
+-------------------------------------
+$ git branch -D crazy-idea
+-------------------------------------
+Branches are cheap and easy, so this is a good way to try something
+out.
-Packing your repository
------------------------
+Using git for collaboration
+---------------------------
-Earlier, we saw that one file under .git/objects/??/ directory
-is stored for each git object you create. This representation
-is convenient and efficient to create atomically and safely, but
-not so convenient to transport over the network. Since git objects are
-immutable once they are created, there is a way to optimize the
-storage by "packing them together". The command
+Suppose that Alice has started a new project with a git repository in
+/home/alice/project, and that Bob, who has a home directory on the
+same machine, wants to contribute.
- git repack
+Bob begins with:
-will do it for you. If you followed the tutorial examples, you
-would have accumulated about 17 objects in .git/objects/??/
-directories by now. "git repack" tells you how many objects it
-packed, and stores the packed file in .git/objects/pack
-directory.
+------------------------------------------------
+$ git clone /home/alice/project myrepo
+------------------------------------------------
-[ Side Note: you will see two files, pack-*.pack and pack-*.idx,
- in .git/objects/pack directory. They are closely related to
- each other, and if you ever copy them by hand to a different
- repository for whatever reason, you should make sure you copy
- them together. The former holds all the data from the objects
- in the pack, and the latter holds the index for random
- access. ]
+This creates a new directory "myrepo" containing a clone of Alice's
+repository. The clone is on an equal footing with the original
+project, posessing its own copy of the original project's history.
-If you are paranoid, running "git-verify-pack" command would
-detect if you have a corrupt pack, but do not worry too much.
-Our programs are always perfect ;-).
+Bob then makes some changes and commits them:
-Once you have packed objects, you do not need to leave the
-unpacked objects that are contained in the pack file anymore.
+------------------------------------------------
+(edit files)
+$ git commit -a
+(repeat as necessary)
+------------------------------------------------
- git prune-packed
+When he's ready, he tells Alice to pull changes from the repository
+at /home/bob/myrepo. She does this with:
-would remove them for you.
+------------------------------------------------
+$ cd /home/alice/project
+$ git pull /home/bob/myrepo
+------------------------------------------------
-You can try running "find .git/objects -type f" before and after
-you run "git prune-packed" if you are curious.
+This actually pulls changes from the branch in Bob's repository named
+"master". Alice could request a different branch by adding the name
+of the branch to the end of the git pull command line.
-[ Side Note: "git pull" is slightly cumbersome for HTTP transport,
- as a packed repository may contain relatively few objects in a
- relatively large pack. If you expect many HTTP pulls from your
- public repository you might want to repack & prune often, or
- never. ]
+This merges Bob's changes into her repository; "git whatchanged" will
+now show the new commits. If Alice has made her own changes in the
+meantime, then Bob's changes will be merged in, and she will need to
+manually fix any conflicts.
-If you run "git repack" again at this point, it will say
-"Nothing to pack". Once you continue your development and
-accumulate the changes, running "git repack" again will create a
-new pack, that contains objects created since you packed your
-repository the last time. We recommend that you pack your project
-soon after the initial import (unless you are starting your
-project from scratch), and then run "git repack" every once in a
-while, depending on how active your project is.
+A more cautious Alice might wish to examine Bob's changes before
+pulling them. She can do this by creating a temporary branch just
+for the purpose of studying Bob's changes:
-When a repository is synchronized via "git push" and "git pull",
-objects packed in the source repository are usually stored
-unpacked in the destination, unless rsync transport is used.
+-------------------------------------
+$ git fetch /home/bob/myrepo master:bob-incoming
+-------------------------------------
+which fetches the changes from Bob's master branch into a new branch
+named bob-incoming. (Unlike git pull, git fetch just fetches a copy
+of Bob's line of development without doing any merging). Then
-Working with Others
--------------------
+-------------------------------------
+$ git whatchanged -p master..bob-incoming
+-------------------------------------
-Although git is a truly distributed system, it is often
-convenient to organize your project with an informal hierarchy
-of developers. Linux kernel development is run this way. There
-is a nice illustration (page 17, "Merges to Mainline") in Randy
-Dunlap's presentation (http://tinyurl.com/a2jdg).
+shows a list of all the changes that Bob made since he branched from
+Alice's master branch.
-It should be stressed that this hierarchy is purely "informal".
-There is nothing fundamental in git that enforces the "chain of
-patch flow" this hierarchy implies. You do not have to pull
-from only one remote repository.
+After examing those changes, and possibly fixing things, Alice can
+pull the changes into her master branch:
+-------------------------------------
+$ git checkout master
+$ git pull . bob-incoming
+-------------------------------------
-A recommended workflow for a "project lead" goes like this:
+The last command is a pull from the "bob-incoming" branch in Alice's
+own repository.
- (1) Prepare your primary repository on your local machine. Your
- work is done there.
+Later, Bob can update his repo with Alice's latest changes using
- (2) Prepare a public repository accessible to others.
+-------------------------------------
+$ git pull
+-------------------------------------
- (3) Push into the public repository from your primary
- repository.
+Note that he doesn't need to give the path to Alice's repository;
+when Bob cloned Alice's repository, git stored the location of her
+repository in the file .git/remotes/origin, and that location is used
+as the default for pulls.
- (4) "git repack" the public repository. This establishes a big
- pack that contains the initial set of objects as the
- baseline, and possibly "git prune-packed" if the transport
- used for pulling from your repository supports packed
- repositories.
+Bob may also notice a branch in his repository that he didn't create:
- (5) Keep working in your primary repository. Your changes
- include modifications of your own, patches you receive via
- e-mails, and merges resulting from pulling the "public"
- repositories of your "subsystem maintainers".
+-------------------------------------
+$ git branch
+* master
+ origin
+-------------------------------------
- You can repack this private repository whenever you feel
- like.
+The "origin" branch, which was created automatically by "git clone",
+is a pristine copy of Alice's master branch; Bob should never commit
+to it.
- (6) Push your changes to the public repository, and announce it
- to the public.
+If Bob later decides to work from a different host, he can still
+perform clones and pulls using the ssh protocol:
- (7) Every once in a while, "git repack" the public repository.
- Go back to step (5) and continue working.
+-------------------------------------
+$ git clone alice.org:/home/alice/project myrepo
+-------------------------------------
+Alternatively, git has a native protocol, or can use rsync or http;
+see gitlink:git-pull[1] for details.
-A recommended work cycle for a "subsystem maintainer" who works
-on that project and has an own "public repository" goes like this:
+Git can also be used in a CVS-like mode, with a central repository
+that various users push changes to; see gitlink:git-push[1] and
+link:cvs-migration.html[git for CVS users].
- (1) Prepare your work repository, by "git clone" the public
- repository of the "project lead". The URL used for the
- initial cloning is stored in .git/branches/origin.
+Keeping track of history
+------------------------
- (2) Prepare a public repository accessible to others.
+Git history is represented as a series of interrelated commits. The
+most recent commit in the currently checked-out branch can always be
+referred to as HEAD, and the "parent" of any commit can always be
+referred to by appending a caret, "^", to the end of the name of the
+commit. So, for example,
- (3) Copy over the packed files from "project lead" public
- repository to your public repository by hand; preferrably
- use rsync for that task.
+-------------------------------------
+git diff HEAD^ HEAD
+-------------------------------------
- (4) Push into the public repository from your primary
- repository. Run "git repack", and possibly "git
- prune-packed" if the transport used for pulling from your
- repository supports packed repositories.
+shows the difference between the most-recently checked-in state of
+the tree and the previous state, and
- (5) Keep working in your primary repository. Your changes
- include modifications of your own, patches you receive via
- e-mails, and merges resulting from pulling the "public"
- repositories of your "project lead" and possibly your
- "sub-subsystem maintainers".
+-------------------------------------
+git diff HEAD^^ HEAD^
+-------------------------------------
- You can repack this private repository whenever you feel
- like.
+shows the difference between that previous state and the state two
+commits ago. Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret},
+and more generally HEAD~n can refer to the nth previous commit.
+Commits representing merges have more than one parent, and you can
+specify which parent to follow in that case; see
+gitlink:git-rev-parse[1].
- (6) Push your changes to your public repository, and ask your
- "project lead" and possibly your "sub-subsystem
- maintainers" to pull from it.
+The name of a branch can also be used to refer to the most recent
+commit on that branch; so you can also say things like
- (7) Every once in a while, "git repack" the public repository.
- Go back to step (5) and continue working.
+-------------------------------------
+git diff HEAD experimental
+-------------------------------------
+to see the difference between the most-recently committed tree in
+the current branch and the most-recently committed tree in the
+experimental branch.
-A recommended work cycle for an "individual developer" who does
-not have a "public" repository is somewhat different. It goes
-like this:
+But you may find it more useful to see the list of commits made in
+the experimental branch but not in the current branch, and
- (1) Prepare your work repository, by "git clone" the public
- repository of the "project lead" (or a "subsystem
- maintainer", if you work on a subsystem). The URL used for
- the initial cloning is stored in .git/branches/origin.
+-------------------------------------
+git whatchanged HEAD..experimental
+-------------------------------------
- (2) Do your work there. Make commits.
+will do that, just as
- (3) Run "git fetch origin" from the public repository of your
- upstream every once in a while. This does only the first
- half of "git pull" but does not merge. The head of the
- public repository is stored in .git/refs/heads/origin.
+-------------------------------------
+git whatchanged experimental..HEAD
+-------------------------------------
- (4) Use "git cherry origin" to see which ones of your patches
- were accepted, and/or use "git rebase origin" to port your
- unmerged changes forward to the updated upstream.
+will show the list of commits made on the HEAD but not included in
+experimental.
- (5) Use "git format-patch origin" to prepare patches for e-mail
- submission to your upstream and send it out. Go back to
- step (2) and continue.
+You can also give commits convenient names of your own: after running
+-------------------------------------
+$ git-tag v2.5 HEAD^^
+-------------------------------------
-Working with Others, Shared Repository Style
---------------------------------------------
+you can refer to HEAD^^ by the name "v2.5". If you intend to share
+this name with other people (for example, to identify a release
+version), you should create a "tag" object, and perhaps sign it; see
+gitlink:git-tag[1] for details.
-If you are coming from CVS background, the style of cooperation
-suggested in the previous section may be new to you. You do not
-have to worry. git supports "shared public repository" style of
-cooperation you are probably more familiar with as well.
+You can revisit the old state of a tree, and make further
+modifications if you wish, using git branch: the command
-For this, set up a public repository on a machine that is
-reachable via SSH by people with "commit privileges". Put the
-committers in the same user group and make the repository
-writable by that group.
+-------------------------------------
+$ git branch stable-release v2.5
+-------------------------------------
-Each committer would then:
+will create a new branch named "stable-release" starting from the
+commit which you tagged with the name v2.5.
- - clone the shared repository to a local repository,
+You can reset the state of any branch to an earlier commit at any
+time with
-------------------------------------------------
-$ git clone repo.shared.xz:/pub/scm/project.git/ my-project
-$ cd my-project
-$ hack away
-------------------------------------------------
+-------------------------------------
+$ git reset --hard v2.5
+-------------------------------------
- - merge the work others might have done while you were
- hacking away.
+This will remove all later commits from this branch and reset the
+working tree to the state it had when the given commit was made. If
+this branch is the only branch containing the later commits, those
+later changes will be lost. Don't use "git reset" on a
+publicly-visible branch that other developers pull from, as git will
+be confused by history that disappears in this way.
-------------------------------------------------
-$ git pull origin
-$ test the merge result
-------------------------------------------------
+Next Steps
+----------
- - push your work as the new head of the shared
- repository.
+Some good commands to explore next:
-------------------------------------------------
-$ git push origin master
-------------------------------------------------
+ * gitlink:git-diff[1]: This flexible command does much more than
+ we've seen in the few examples above.
-If somebody else pushed into the same shared repository while
-you were working locally, the last step "git push" would
-complain, telling you that the remote "master" head does not
-fast forward. You need to pull and merge those other changes
-back before you push your work when it happens.
+ * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
+ series of git commits into emailed patches, and vice versa,
+ useful for projects such as the linux kernel which rely heavily
+ on emailed patches.
+ * gitlink:git-bisect[1]: When there is a regression in your
+ project, one way to track down the bug is by searching through
+ the history to find the exact commit that's to blame. Git bisect
+ can help you perform a binary search for that commit. It is
+ smart enough to perform a close-to-optimal search even in the
+ case of complex non-linear history with lots of merged branches.
-[ to be continued.. cvsimports ]
+Other good starting points include link:everyday.html[Everday GIT
+with 20 Commands Or So] and link:cvs-migration.html[git for CVS
+users]. Also, link:core-tutorial.html[A short git tutorial] gives an
+introduction to lower-level git commands for advanced users and
+developers.