-A short git tutorial
-====================
-May 2005
+A tutorial introduction to git
+==============================
+This tutorial explains how to import a new project into git, make
+changes to it, and share changes with other developers.
-Introduction
-------------
+First, note that you can get documentation for a command such as "git
+diff" with:
-This is trying to be a short tutorial on setting up and using a git
-archive, mainly because being hands-on and using explicit examples is
-often the best way of explaining what is going on.
+------------------------------------------------
+$ man git-diff
+------------------------------------------------
-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.
+Importing a new project
+-----------------------
-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...
+Assume you have a tarball project.tar.gz with your initial work. You
+can place it under git revision control as follows.
+------------------------------------------------
+$ tar xzf project.tar.gz
+$ cd project
+$ git init-db
+------------------------------------------------
-Creating a git archive
-----------------------
+Git will reply
-Creating a new git archive couldn't be easier: all git archives 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.
+------------------------------------------------
+defaulting to local storage area
+------------------------------------------------
-For our first example, we're going to start a totally new archive 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":
+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
- mkdir git-tutorial
- cd git-tutorial
- git-init-db
+------------------------------------------------
+$ git add .
+------------------------------------------------
-to which git will reply
+Finally,
- defaulting to local storage area
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
-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:
+will prompt you for a commit message, then record the current state
+of all the files to the repository.
- - a symlink called HEAD, pointing to "refs/heads/master"
+Try modifying some files, then run
- 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.
+------------------------------------------------
+$ git diff
+------------------------------------------------
- - a subdirectory called "objects", which will contain all the git SHA1
- 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.
+to review your changes. When you're done,
- - a subdirectory called "refs", which contains references to objects.
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
- 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 of your
- repository.
+will again prompt your for a message describing the change, and then
+record the new versions of the modified files.
- 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.
+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.
- 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.
+To add a new file, first create the file, then
- [ 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 ]
+------------------------------------------------
+$ git add path/to/new/file
+------------------------------------------------
-You have now created your first git archive. Of course, since it's
-empty, that's not very useful, so let's start populating it with data.
+then commit as usual. No special command is required when removing a
+file; just remove it, then commit.
+At any point you can view the history of your changes using
- Populating a git archive
- ------------------------
+------------------------------------------------
+$ git log
+------------------------------------------------
-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.
+If you also want to see complete diffs at each step, use
-Start off with just creating any random files that you want to maintain
-in your git archive. We'll start off with a few bad examples, just to
-get a feel for how this works:
+------------------------------------------------
+$ git log -p
+------------------------------------------------
- echo "Hello World" > a
- echo "Silly example" > b
+Managing branches
+-----------------
-you have now created two files in your working directory, but to
-actually check in your hard work, you will have to go through two steps:
+A single git repository can maintain multiple branches of
+development. To create a new branch named "experimental", use
- - fill in the "cache" aka "index" file with the information about your
- working directory state
+------------------------------------------------
+$ git branch experimental
+------------------------------------------------
- - commit that index file as an object.
+If you now run
-The first step is trivial: when you want to tell git about any changes
-to your working directory, 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.
+------------------------------------------------
+$ git branch
+------------------------------------------------
-So to populate the index with the two files you just created, you can do
+you'll get a list of all existing branches:
- git-update-cache --add a b
+------------------------------------------------
+ experimental
+* master
+------------------------------------------------
-and you have now told git to track those two files.
+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
-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
-store. If you did exactly the steps above, you should now be able to do
+------------------------------------------------
+$ git checkout experimental
+------------------------------------------------
- ls .git/objects/??/*
+to switch to the experimental branch. Now edit a file, commit the
+change, and switch back to the master branch:
-and see two files:
+------------------------------------------------
+(edit file)
+$ git commit -a
+$ git checkout master
+------------------------------------------------
- .git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
- .git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
+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.
-which correspond with the object with SHA1 names of 557db... and f24c7..
-respectively.
+You can make a different change on the master branch:
-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:
+------------------------------------------------
+(edit file)
+$ git commit -a
+------------------------------------------------
- git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
+at this point the two branches have diverged, with different changes
+made in each. To merge the changes made in the two branches, run
-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 pull . experimental
+------------------------------------------------
- git-cat-file "blob" 557db03de997c86a4a028e1ebd3a1ceb225be238
+If the changes don't conflict, you're done. If there are conflicts,
+markers will be left in the problematic files showing the conflict;
-which will print out "Hello World". The object 557db... is nothing
-more than the contents of your file "a".
+------------------------------------------------
+$ git diff
+------------------------------------------------
-[ Digression: don't confuse that object with the file "a" itself. The
- object is literally just those specific _contents_ of the file, and
- however much you later change the contents in file "a", the object we
- just looked at will never change. Objects are immutable. ]
+will show this. Once you've edited the files to resolve the
+conflicts,
-Anyway, as we mentioned previously, you normally never actually take a
-look at the objects themselves, and typing long 40-character hex SHA1
-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 content
-store.
+------------------------------------------------
+$ git commit -a
+------------------------------------------------
-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.
+will commit the result of the merge. Finally,
-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.
+------------------------------------------------
+$ gitk
+------------------------------------------------
-In particular, let's not even check in the two files into git yet, we'll
-start off by adding another line to "a" first:
+will show a nice graphical representation of the resulting history.
- echo "It's a new day for git" >> a
+If you develop on a branch crazy-idea, then regret it, you can always
+delete the branch with
-and you can now, since you told git about the previous state of "a", ask
-git what has changed in the tree compared to your old index, using the
-"git-diff-files" command:
+-------------------------------------
+$ git branch -D crazy-idea
+-------------------------------------
- git-diff-files
+Branches are cheap and easy, so this is a good way to try something
+out.
-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 "a" has been modified, and that the old object
-contents it had have been replaced with something else.
+Using git for collaboration
+---------------------------
-To make it readable, we can tell git-diff-files to output the
-differences as a patch, using the "-p" flag:
+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-diff-files -p
+Bob begins with:
-which will spit out
+------------------------------------------------
+$ git clone /home/alice/project myrepo
+------------------------------------------------
- diff --git a/a b/a
- --- a/a
- +++ b/a
- @@ -1 +1,2 @@
- Hello World
- +It's a new day for git
+This creates a new directory "myrepo" containing a clone of Alice's
+repository. The clone is on an equal footing with the original
+project, possessing its own copy of the original project's history.
-ie the diff of the change we caused by adding another line to "a".
+Bob then makes some changes and commits them:
-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.
+------------------------------------------------
+(edit files)
+$ git commit -a
+(repeat as necessary)
+------------------------------------------------
+When he's ready, he tells Alice to pull changes from the repository
+at /home/bob/myrepo. She does this with:
- Committing git state
- --------------------
+------------------------------------------------
+$ cd /home/alice/project
+$ git pull /home/bob/myrepo
+------------------------------------------------
-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.
+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.
-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:
+This merges Bob's changes into her repository; "git log" 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.
- git-write-tree
+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:
-and this will just output the name of the resulting tree, in this case
-(if you have does exactly as I've described) it should be
+-------------------------------------
+$ git fetch /home/bob/myrepo master:bob-incoming
+-------------------------------------
- 3ede4ed7e895432c0a247f09d71a76db53bd0fa4
-
-which is another incomprehensible object name. Again, if you want to,
-you can use "git-cat-file -t 3ede4.." 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 archive, and it has no parents, we only need to pass in
-the tree ID. However, git-commit-tree also wants to get a commit message
-on its standard input, and it will write out the resulting ID for the
-commit to its standard output.
-
-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:
-
- echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD
-
-which will say:
-
- Committing initial tree 3ede4ed7e895432c0a247f09d71a76db53bd0fa4
-
-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.
+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
+-------------------------------------
+$ git log -p master..bob-incoming
+-------------------------------------
- Making a change
- ---------------
-
-Remember how we did the "git-update-cache" on file "a" and then we
-changed "a" afterward, and could compare the new state of "a" with the
-state we saved in the index file?
-
-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 "a", not the new ones. We did
-that on purpose, to show the difference between the index state, and the
-state in the working directory, and how they don't have to match, even
-when we commit things.
-
-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".
-
-Unlike "git-diff-files", which showed the difference between the index
-file and the working directory, "git-diff-cache" shows the differences
-between a committed _tree_ and the index file. 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.
-
-But now we can do
-
- 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 not comparing against the index file, we're comparing against
-the tree we just wrote. It just so happens that those two are obviously
-the same.
-
-"git-diff-cache" also has a specific flag "--cached", which is used to
-tell it to show the differences purely with the index file, and ignore
-the current working directory 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.
-
-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
-directory contents", "index file" and "committed tree". We have changes
-in the working directory 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:
-
- git-update-cache a
-
-(note how we didn't need the "--add" flag this time, since git knew
-about the file already).
-
-Note what happens to the different git-diff-xxx versions here. After
-we've updated "a" 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 directory.
-
-Now, since we've updated "a" in the index, we can commit the new
-version. We could do it by writing the tree by hand, 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 the fact is, git has a simple helper
-script for doing all of the non-initial commits that does all of this
-for you, and starts up an editor to let you write your commit message
-yourself, so let's just use that:
-
- git commit
-
-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.
-
-(Btw, current versions of git will consider the change in question to be
-so big that it's considered a whole new file, since the diff is actually
-bigger than the file. So the helpful comments that git-commit-script
-tells you for this example will say that you deleted and re-created the
-file "a". For a less contrived example, these things are usually more
-obvious).
+shows a list of all the changes that Bob made since he branched from
+Alice's master branch.
-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.
-
-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
-activity.
+After examining those changes, and possibly fixing things, Alice can
+pull the changes into her master branch:
-To see the whole history of our pitiful little git-tutorial project, you
-can do
+-------------------------------------
+$ git checkout master
+$ git pull . bob-incoming
+-------------------------------------
- git log
+The last command is a pull from the "bob-incoming" branch in Alice's
+own repository.
-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.
+Later, Bob can update his repo with Alice's latest changes using
-[ 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 pull
+-------------------------------------
-With that, you should now be having some inkling of what git does, and
-can explore on your own.
+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.
+Bob may also notice a branch in his repository that he didn't create:
- Copying archives
- -----------------
+-------------------------------------
+$ git branch
+* master
+ origin
+-------------------------------------
-Git archives 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.
+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.
-[ 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 directory that it describes" may not be technically 100%
- accurate, but it's a good model for all normal use ]
+If Bob later decides to work from a different host, he can still
+perform clones and pulls using the ssh protocol:
-This has two implications:
+-------------------------------------
+$ git clone alice.org:/home/alice/project myrepo
+-------------------------------------
- - if you grow bored with the tutorial archive you created (or you've
- made a mistake and want to start all over), you can just do simple
+Alternatively, git has a native protocol, or can use rsync or http;
+see gitlink:git-pull[1] for details.
- rm -rf git-tutorial
+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].
- and it will be gone. There's no external repository, and there's no
- history outside of the project you created.
+Exploring history
+-----------------
- - if you want to move or duplicate a git archive, you can do so. There
- is no "git clone" command: if you want to create a copy of your
- archive (with all the full history that went along with it), you can
- do so with a regular "cp -a git-tutorial new-git-tutorial".
+Git history is represented as a series of interrelated commits. We
+have already seen that the git log command can list those commits.
+Note that first line of each git log entry also gives a name for the
+commit:
- Note that when you've moved or copied a git archive, 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 log
+commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
+Author: Junio C Hamano <junkio@cox.net>
+Date: Tue May 16 17:18:22 2006 -0700
- git-update-cache --refresh
+ merge-base: Clarify the comments on post processing.
+-------------------------------------
- to make sure that the index file is up-to-date in the new one.
+We can give this name to git show to see the details about this
+commit.
-Note that the second point is true even across machines. You can
-duplicate a remote git archive with _any_ regular copy mechanism, be it
-"scp", "rsync" or "wget".
+-------------------------------------
+$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
+-------------------------------------
-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
+But there other ways to refer to commits. You can use any initial
+part of the name that is long enough to uniquely identify the commit:
- git-read-tree HEAD
- git-update-cache --refresh
+-------------------------------------
+$ git show c82a22c39c # the first few characters of the name are
+ # usually enough
+$ git show HEAD # the tip of the current branch
+$ git show experimental # the tip of the "experimental" branch
+-------------------------------------
-which will force a total index re-build from the tree pointed to by
-HEAD.
+Every commit has at least one "parent" commit, which points to the
+previous state of the project:
-In fact, many 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.
+-------------------------------------
+$ git show HEAD^ # to see the parent of HEAD
+$ git show HEAD^^ # to see the grandparent of HEAD
+$ git show HEAD~4 # to see the great-great grandparent of HEAD
+-------------------------------------
-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
+Note that merge commits may have more than one parent:
- mkdir my-git
- cd my-git
- rsync -rL rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/git.git/ .git
+-------------------------------------
+$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
+$ git show HEAD^2 # show the second parent of HEAD
+-------------------------------------
-followed by
+You can also give commits names of your own; after running
- git-read-tree HEAD
+-------------------------------------
+$ git-tag v2.5 1b2e1d63ff
+-------------------------------------
-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_directory_ files to work on. To get
-those, you'd check them out with
+you can refer to 1b2e1d63ff 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.
- git-checkout-cache -u -a
+Any git command that needs to know a commit can take any of these
+names. For example:
-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" file 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"
-file first, to tell git-checkout-cache to _force_ overwriting of any old
-files).
+-------------------------------------
+$ git diff v2.5 HEAD # compare the current HEAD to v2.5
+$ git branch stable v2.5 # start a new branch named "stable" based
+ # at v2.5
+$ git reset --hard HEAD^ # reset your current branch and working
+ # directory to its state at HEAD^
+-------------------------------------
-You have now successfully copied somebody else's (mine) remote
-repository, and checked it out.
+Be careful with that last command: in addition to losing any changes
+in the working directory, it will also remove all later commits from
+this branch. If this branch is the only branch containing those
+commits, they will be lost. (Also, 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.)
-[ to be continued.. cvs2git, tagging versions, branches, merging.. ]
+The git grep command can search for strings in any version of your
+project, so
+
+-------------------------------------
+$ git grep "hello" v2.5
+-------------------------------------
+
+searches for all occurrences of "hello" in v2.5.
+
+If you leave out the commit name, git grep will search any of the
+files it manages in your current directory. So
+
+-------------------------------------
+$ git grep "hello"
+-------------------------------------
+
+is a quick way to search just the files that are tracked by git.
+
+Many git commands also take sets of commits, which can be specified
+in a number of ways. Here are some examples with git log:
+
+-------------------------------------
+$ git log v2.5..v2.6 # commits between v2.5 and v2.6
+$ git log v2.5.. # commits since v2.5
+$ git log --since="2 weeks ago" # commits from the last 2 weeks
+$ git log v2.5.. Makefile # commits since v2.5 which modify
+ # Makefile
+-------------------------------------
+
+You can also give git log a "range" of commits where the first is not
+necessarily an ancestor of the second; for example, if the tips of
+the branches "stable-release" and "master" diverged from a common
+commit some time ago, then
+
+-------------------------------------
+$ git log stable..experimental
+-------------------------------------
+
+will list commits made in the experimental branch but not in the
+stable branch, while
+
+-------------------------------------
+$ git log experimental..stable
+-------------------------------------
+
+will show the list of commits made on the stable branch but not
+the experimental branch.
+
+The "git log" command has a weakness: it must present commits in a
+list. When the history has lines of development that diverged and
+then merged back together, the order in which "git log" presents
+those commits is meaningless.
+
+Most projects with multiple contributors (such as the linux kernel,
+or git itself) have frequent merges, and gitk does a better job of
+visualizing their history. For example,
+
+-------------------------------------
+$ gitk --since="2 weeks ago" drivers/
+-------------------------------------
+
+allows you to browse any commits from the last 2 weeks of commits
+that modified files under the "drivers" directory. (Note: you can
+adjust gitk's fonts by holding down the control key while pressing
+"-" or "+".)
+
+Finally, most commands that take filenames will optionally allow you
+to precede any filename by a commit, to specify a particular version
+of the file:
+
+-------------------------------------
+$ git diff v2.5:Makefile HEAD:Makefile.in
+-------------------------------------
+
+You can also use "git cat-file -p" to see any such file:
+
+-------------------------------------
+$ git cat-file -p v2.5:Makefile
+-------------------------------------
+
+Next Steps
+----------
+
+This tutorial should be enough to perform basic distributed revision
+control for your projects. However, to fully understand the depth
+and power of git you need to understand two simple ideas on which it
+is based:
+
+ * The object database is the rather elegant system used to
+ store the history of your project--files, directories, and
+ commits.
+
+ * The index file is a cache of the state of a directory tree,
+ used to create commits, check out working directories, and
+ hold the various trees involved in a merge.
+
+link:tutorial-2.html[Part two of this tutorial] explains the object
+database, the index file, and a few other odds and ends that you'll
+need to make the most of git.
+
+If you don't want to consider with that right away, a few other
+digressions that may be interesting at this point are:
+
+ * 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.
+
+ * link:everyday.html[Everyday GIT with 20 Commands Or So]
+
+ * link:cvs-migration.html[git for CVS users].
projects / git.git / blobdiff