git add <pathspec>... defaults to "-A"
[gitweb.git] / Documentation / gitcore-tutorial.txt
index 5325c5a7d5cab3f74c3866319a60d35e4299da2e..f538a870c72dec8a022c23d5023cf5252e9925cf 100644 (file)
@@ -3,7 +3,7 @@ gitcore-tutorial(7)
 
 NAME
 ----
-gitcore-tutorial - A git core tutorial for developers
+gitcore-tutorial - A Git core tutorial for developers
 
 SYNOPSIS
 --------
@@ -12,17 +12,17 @@ git *
 DESCRIPTION
 -----------
 
-This tutorial explains how to use the "core" git commands to set up and
-work with a git repository.
+This tutorial explains how to use the "core" Git commands to set up and
+work with a Git repository.
 
-If you just need to use git as a revision control system you may prefer
-to start with "A Tutorial Introduction to GIT" (linkgit:gittutorial[7]) or
-link:user-manual.html[the GIT User Manual].
+If you just need to use Git as a revision control system you may prefer
+to start with "A Tutorial Introduction to Git" (linkgit:gittutorial[7]) or
+link:user-manual.html[the Git User Manual].
 
 However, an understanding of these low-level tools can be helpful if
-you want to understand git's internals.
+you want to understand Git's internals.
 
-The core git is often called "plumbing", with the prettier user
+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.
@@ -40,19 +40,19 @@ Deeper technical details are often marked as Notes, which you can
 skip on your first reading.
 
 
-Creating a git repository
+Creating a Git repository
 -------------------------
 
-Creating a new git repository couldn't be easier: all git repositories start
+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.
+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':
+subdirectory, and initialize the Git infrastructure with 'git init':
 
 ------------------------------------------------
 $ mkdir git-tutorial
@@ -60,13 +60,13 @@ $ cd git-tutorial
 $ git init
 ------------------------------------------------
 
-to which git will reply
+to which Git will reply
 
 ----------------
 Initialized empty Git repository in .git/
 ----------------
 
-which is just git's way of saying that you haven't been doing anything
+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, it should show you
@@ -102,13 +102,13 @@ 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
+branch. A number of the Git tools will assume that `.git/HEAD` is
 valid, though.
 
 [NOTE]
-An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
+An 'object' is identified by its 160-bit SHA-1 hash, aka 'object name',
 and a reference to an object is always the 40-byte hex
-representation of that SHA1 name. The files in the `refs`
+representation of that SHA-1 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
@@ -119,18 +119,18 @@ populating your tree.
 An advanced user may want to take a look at linkgit:gitrepository-layout[5]
 after finishing this tutorial.
 
-You have now created your first git repository. Of course, since it's
+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
+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
+in your Git repository. We'll start off with a few bad examples, just to
 get a feel for how this works:
 
 ------------------------------------------------
@@ -146,7 +146,7 @@ but to actually check in your hard work, you will have to go through two steps:
 
  - commit that index file as an object.
 
-The first step is trivial: when you want to tell git about any changes
+The first step is trivial: when you want to tell Git about any changes
 to your working tree, you use the 'git update-index' 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 index
@@ -160,10 +160,10 @@ So to populate the index with the two files you just created, you can do
 $ git update-index --add hello example
 ------------------------------------------------
 
-and you have now told git to track those two files.
+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
+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
 
 
@@ -189,7 +189,7 @@ $ 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 (i.e., just a
+object is. Git will tell you that you have a "blob" object (i.e., just a
 regular file), and you can see the contents with
 
 ----------------
@@ -214,28 +214,28 @@ 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-index' did something magical, and
-actually saved away the contents of your files into the git object
+actually saved away the contents of your files into the Git object
 database.
 
 Updating the index 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.
+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.
+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.
 
-In particular, let's not even check in the two files into git yet, we'll
+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:
 
 ------------------------------------------------
 $ echo "It's a new day for git" >>hello
 ------------------------------------------------
 
-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
+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:
 
 ------------
@@ -282,11 +282,11 @@ index 557db03..263414f 100644
 ------------
 
 
-Committing git state
+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
+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.
@@ -296,7 +296,7 @@ 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:
+creating the equivalent of a Git "directory" object:
 
 ------------------------------------------------
 $ git write-tree
@@ -415,9 +415,9 @@ 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
+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
+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.
 ================
@@ -433,7 +433,7 @@ update the index cache:
 $ git update-index hello
 ------------------------------------------------
 
-(note how we didn't need the `--add` flag this time, since git knew
+(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-{asterisk}' versions here.
@@ -464,7 +464,7 @@ this point (you can continue to edit things and update the index), you
 can just leave an empty message. Otherwise `git commit` will commit
 the change for you.
 
-You've now made your first real git commit. And if you're interested in
+You've now made your first real Git commit. And if you're interested in
 looking at what `git commit` 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
@@ -535,7 +535,7 @@ 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
+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
@@ -563,19 +563,19 @@ the log.showroot configuration variable to false. Having this, you
 can still show it for each command just adding the `--root` option,
 which is a flag for 'git diff-tree' accepted by both commands.
 
-With that, you should now be having some inkling of what git does, and
+With that, you should now be having some inkling of what Git does, and
 can explore on your own.
 
 [NOTE]
 Most likely, you are not directly using the core
-git Plumbing commands, but using Porcelain such as 'git add', `git-rm'
+Git Plumbing commands, but using Porcelain such as 'git add', `git-rm'
 and `git-commit'.
 
 
 Tagging a version
 -----------------
 
-In git, there are two kinds of tags, a "light" one, and an "annotated tag".
+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`.
@@ -598,7 +598,7 @@ 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
+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
@@ -623,17 +623,17 @@ name for the state at that point.
 Copying repositories
 --------------------
 
-git repositories are normally totally self-sufficient and relocatable.
+Git repositories are normally totally self-sufficient and relocatable.
 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`
+"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.
 
 [NOTE]
-You can tell git to split the git internal information from
+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
+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.
 
@@ -649,13 +649,13 @@ $ 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
+ - 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
+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
@@ -667,7 +667,7 @@ $ git update-index --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
+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
@@ -694,23 +694,23 @@ The above can also be written as simply
 $ git reset
 ----------------
 
-and in fact a lot of the common git command combinations can be scripted
+and in fact a lot of the common Git command combinations can be scripted
 with the `git xyz` interfaces.  You can learn things by just looking
 at what the various git scripts do.  For example, `git reset` used to be
 the above two lines implemented in 'git reset', but some things like
 'git status' and 'git commit' are slightly more complex scripts around
-the basic git commands.
+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
+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
+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
+create your own copy of the Git repository, you'd do the following
 
 ----------------
 $ mkdir my-git
@@ -725,7 +725,7 @@ $ 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
+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
 
@@ -757,13 +757,13 @@ repository, and checked it out.
 Creating a new branch
 ---------------------
 
-Branches in git are really nothing more than pointers into the git
+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
+point in the project history, and just writing the SHA-1 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,
@@ -849,7 +849,7 @@ $ git commit -m "Some work." -i hello
 Here, we just added another line to `hello`, and we used a shorthand for
 doing both `git update-index hello` and `git commit` by just giving the
 filename directly to `git commit`, with an `-i` flag (it tells
-git to 'include' that file in addition to what you have done to
+Git to 'include' that file in addition to what you have done to
 the index file so far when making the commit).  The `-m` flag is to give the
 commit log message from the command line.
 
@@ -900,7 +900,7 @@ where the first 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
+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:
 
@@ -939,7 +939,7 @@ 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
+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 always work in X-Window
@@ -1028,7 +1028,7 @@ 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
+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 merge'. In fact, a remote merge ends up being nothing
 more than "fetch the work from a remote repository into a temporary tag"
@@ -1068,7 +1068,7 @@ and requires you to have a log-in privilege over `ssh` to the
 remote machine.  It finds out the set of objects the other side
 lacks by exchanging the head commits both ends have and
 transfers (close to) minimum set of objects.  It is by far the
-most efficient way to exchange git objects between repositories.
+most efficient way to exchange Git objects between repositories.
 
 Local directory::
        `/path/to/repo.git/`
@@ -1077,7 +1077,7 @@ This transport is the same as SSH transport but uses 'sh' to run
 both ends on the local machine instead of running other end on
 the remote machine via 'ssh'.
 
-git Native::
+Git Native::
        `git://remote.machine/path/to/repo.git/`
 +
 This transport was designed for anonymous downloading.  Like SSH
@@ -1099,8 +1099,8 @@ necessary objects.  Because of this behavior, they are
 sometimes also called 'commit walkers'.
 +
 The 'commit walkers' are sometimes also called 'dumb
-transports', because they do not require any git aware smart
-server like git Native transport does.  Any stock HTTP server
+transports', because they do not require any Git aware smart
+server like Git Native transport does.  Any stock HTTP server
 that does not even support directory index would suffice.  But
 you must prepare your repository with 'git update-server-info'
 to help dumb transport downloaders.
@@ -1233,7 +1233,7 @@ file (the first tree goes to stage 1, the second to stage 2,
 etc.).  After reading three trees into three stages, the paths
 that are the same in all three stages are 'collapsed' into stage
 0.  Also paths that are the same in two of three stages are
-collapsed into stage 0, taking the SHA1 from either stage 2 or
+collapsed into stage 0, taking the SHA-1 from either stage 2 or
 stage 3, whichever is different from stage 1 (i.e. only one side
 changed from the common ancestor).
 
@@ -1321,7 +1321,7 @@ update the public repository from it. This is often called
 
 [NOTE]
 This public repository could further be mirrored, and that is
-how git repositories at `kernel.org` are managed.
+how Git repositories at `kernel.org` are managed.
 
 Publishing the changes from your local (private) repository to
 your remote (public) repository requires a write privilege on
@@ -1340,7 +1340,7 @@ done only once.
 on the remote machine. The communication between the two over
 the network internally uses an SSH connection.
 
-Your private repository's git directory is usually `.git`, but
+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
@@ -1350,7 +1350,7 @@ an empty directory:
 $ mkdir my-git.git
 ------------
 
-Then, make that directory into a git repository by running
+Then, make that directory into a Git repository by running
 'git init', but this time, since its name is not the usual
 `.git`, we do things slightly differently:
 
@@ -1389,7 +1389,7 @@ 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.
 
-As a real example, this is how I update my public git
+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:
 
@@ -1402,9 +1402,9 @@ Packing your repository
 -----------------------
 
 Earlier, we saw that one file under `.git/objects/??/` directory
-is stored for each git object you create. This representation
+is stored for each Git object you create. This representation
 is efficient to create atomically and safely, but
-not so convenient to transport over the network. Since git objects are
+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
 
@@ -1472,14 +1472,14 @@ repositories every once in a while.
 Working with Others
 -------------------
 
-Although git is a truly distributed system, it is often
+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
 link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].
 
 It should be stressed that this hierarchy is purely *informal*.
-There is nothing fundamental in git that enforces the "chain of
+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.
 
@@ -1592,7 +1592,7 @@ Working with Others, Shared Repository Style
 
 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
+have to worry. Git supports "shared public repository" style of
 cooperation you are probably more familiar with as well.
 
 See linkgit:gitcvs-migration[7] for the details.
@@ -1602,7 +1602,7 @@ Bundling your work together
 
 It is likely that you will be working on more than one thing at
 a time.  It is easy to manage those more-or-less independent tasks
-using branches with git.
+using branches with Git.
 
 We have already seen how branches work previously,
 with "fun and work" example using two branches.  The idea is the