X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Ftutorial.txt;h=554ee0af912368cb842d93c025e742daaf47f5f2;hb=ae448e3854d8b6e7e37aa88fa3917f5dd97f3210;hp=87feac77e4d2382821d7f711caf05bc20b6fbc34;hpb=ed616049d76a59df10a9064f8883009ab1329da4;p=git.git diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 87feac77..554ee0af 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -1,772 +1,487 @@ -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) +------------------------------------------------ -A common shorthand for "git-diff-files -p" is to just write +When he's ready, he tells Alice to pull changes from the repository +at /home/bob/myrepo. She does this with: - git diff +------------------------------------------------ +$ cd /home/alice/project +$ git pull /home/bob/myrepo +------------------------------------------------ -which will do the same thing. +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. +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. - Committing git state - -------------------- +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: -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. +------------------------------------- +$ git fetch /home/bob/myrepo master:bob-incoming +------------------------------------- -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: +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-write-tree +------------------------------------- +$ git log -p master..bob-incoming +------------------------------------- -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 +shows a list of all the changes that Bob made since he branched from +Alice's master branch. - 3ede4ed7e895432c0a247f09d71a76db53bd0fa4 +After examining those changes, and possibly fixing things, Alice can +pull the changes into her master branch: -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). +------------------------------------- +$ git checkout master +$ git pull . bob-incoming +------------------------------------- -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". +The last command is a pull from the "bob-incoming" branch in Alice's +own repository. -"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. +Later, Bob can update his repo with Alice's latest changes using -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: +------------------------------------- +$ git pull +------------------------------------- - echo "Initial commit" | git-commit-tree $(git-write-tree) > .git/HEAD +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. -which will say: +Bob may also notice a branch in his repository that he didn't create: - Committing initial tree 3ede4ed7e895432c0a247f09d71a76db53bd0fa4 +------------------------------------- +$ git branch +* master + origin +------------------------------------- -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. +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. -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 writtten +If Bob later decides to work from a different host, he can still +perform clones and pulls using the ssh protocol: - git commit +------------------------------------- +$ git clone alice.org:/home/alice/project myrepo +------------------------------------- -instead, and it would have done the above magic scripting for you. +Alternatively, git has a native protocol, or can use rsync or http; +see gitlink:git-pull[1] for details. +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]. - Making a change - --------------- +Exploring history +----------------- -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? +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: -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. +------------------------------------- +$ git log +commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +Author: Junio C Hamano +Date: Tue May 16 17:18:22 2006 -0700 -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". + merge-base: Clarify the comments on post processing. +------------------------------------- -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 either the the index file or the working -directory. 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. +We can give this name to git show to see the details about this +commit. -But now we can do +------------------------------------- +$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 +------------------------------------- - 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 directory 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 directory, but when given the "--cached" flag, it is told to -instead compare against just the index cache contents, 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. - -[ Digression: "git-diff-cache" really always uses the index for its - comparisons, and saying that it compares a tree against the working - directory 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 directory 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. ] +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: -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 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 +------------------------------------- - git-update-cache a +Every commit has at least one "parent" commit, which points to the +previous state of the project: -(note how we didn't need the "--add" flag this time, since git knew -about the file already). +------------------------------------- +$ 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 +------------------------------------- -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. +Note that merge commits may have more than one parent: -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 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: +------------------------------------- +$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^) +$ git show HEAD^2 # show the second parent of HEAD +------------------------------------- - git commit +You can also give commits names of your own; after running -which starts an editor for you to write the commit message and tells you -a bit about what you're doing. +------------------------------------- +$ git-tag v2.5 1b2e1d63ff +------------------------------------- -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 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. -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". +Any git command that needs to know a commit can take any of these +names. For example: -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 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^ +------------------------------------- - git-diff-tree -p HEAD +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.) -(again, "-p" means to show the difference as a human-readable patch), -and it will show what the last commit (in HEAD) actually changed. +The git grep command can search for strings in any version of your +project, so -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. +------------------------------------- +$ git grep "hello" v2.5 +------------------------------------- -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. +searches for all occurrences of "hello" in v2.5. -To see the whole history of our pitiful little git-tutorial project, you -can do +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 - -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 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 +------------------------------------- - git-whatchanged -p --root +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 -and you will see exactly what has changed in the repository over its -short history. +------------------------------------- +$ git log stable..experimental +------------------------------------- -[ 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 ] +will list commits made in the experimental branch but not in the +stable branch, while -With that, you should now be having some inkling of what git does, and -can explore on your own. +------------------------------------- +$ git log experimental..stable +------------------------------------- +will show the list of commits made on the stable branch but not +the experimental branch. - Copying archives - ----------------- +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. -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. +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, -[ 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 ] +------------------------------------- +$ gitk --since="2 weeks ago" drivers/ +------------------------------------- -This has two implications: +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 "+".) - - 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 +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: - rm -rf git-tutorial +------------------------------------- +$ git diff v2.5:Makefile HEAD:Makefile.in +------------------------------------- + +You can also use "git cat-file -p" to see any such file: - and it will be gone. There's no external repository, and there's no - history outside of the project you created. +------------------------------------- +$ git cat-file -p v2.5:Makefile +------------------------------------- - - 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". +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: - 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 + * The object database is the rather elegant system used to + store the history of your project--files, directories, and + commits. - git-update-cache --refresh + * 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. - to make sure that the index file is up-to-date in the new one. +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. -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". +If you don't want to consider with that right away, a few other +digressions that may be interesting at this point are: -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 + * 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. - git-read-tree --reset HEAD - git-update-cache --refresh + * 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. -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). + * link:everyday.html[Everyday GIT with 20 Commands Or So] -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). - -NOTE! 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/linux/kernel/git/torvalds/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_directory_ 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" 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). - -Again, this can all be simplified with - - git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/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 space 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 archive we -used earlier, and create a branch in it. You literally do that by just -creating a new SHA1 reference file, and switch to it by just making the -HEAD pointer point to it: - - cat .git/HEAD > .git/refs/heads/mybranch - ln -sf refs/heads/mybranch .git/HEAD - -and you're done. - -Now, if you make the decision to start your new branch at some other -point in the history than the current HEAD, you usually also want to -actually switch the contents of your working directory to that point -when you switch the head, and "git checkout" will do that for you: -instead of switching the branch by hand with "ln -sf", you can just do - - git checkout mybranch - -which will basically "jump" to the branch specified, update your working -directory to that state, and also make it become the new default HEAD. - -You can always just jump back to your original "master" branch by doing - - git checkout master - -and if you forget which branch you happen to be on, a simple - - ls -l .git/HEAD - -will tell you where it's pointing. - - - 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" >> a - git commit a - -Here, we just added another line to "a", and we used a shorthand for -both going a "git-update-cache a" and "git commit" by just giving the -filename directly to "git commit". - -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 "a", 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" >> a - echo "Lots of fun" >> b - git commit a b - -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 "b" -file, which had no differences in the "mybranch" branch), and say: - - Simple merge failed, trying Automatic merge - Auto-merging a. - merge: warning: conflicts during merge - ERROR: Merge conflict in a. - 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 "a". - -Not to worry. It left the (trivial) conflict in "a" in the same form you -should already be well used to if you've ever used CVS, so let's just -open "a" in our editor (whatever that may be), and fix it up somehow. -I'd suggest just making it so that "a" 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 a - -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. Notive 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. - - - 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 - -and optionally give a branch-name for the remote end as a second -argument. - -[ Todo: fill in real examples ] - - - Tagging a version - ----------------- - -In git, there's two kinds of tags, a "light" one, and a "signed 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 - - cat .git/HEAD > .git/refs/tags/my-first-tag - -after which point you can 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 a "anchor-point" to see what has changed -since you tagged it. - -A "signed 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 a PGP signature that says that yes, you really did -that tag. You create these signed tags with - - git tag - -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 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. - -[ to be continued.. cvsimports, pushing and pulling ] + * link:cvs-migration.html[git for CVS users].