index 5995a2e1525eeee764b5c141b8c558ccba0a953b..059c8ffd272051792f0949a8dc224165d03a1799 100644 (file)
work with a git repository.
If you just need to use git as a revision control system you may prefer
-to start with linkgit:gittutorial[7][a tutorial introduction to git] or
-link:user-manual.html[the git user manual].
+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.
------------------------------------------------
$ mkdir git-tutorial
$ cd git-tutorial
-$ git-init
+$ git init
------------------------------------------------
to which git will reply
populating your tree.
[NOTE]
-An advanced user may want to take a look at the
-link:repository-layout.html[repository layout] document
+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
So to populate the index with the two files you just created, you can do
------------------------------------------------
-$ git-update-index --add hello example
+$ git update-index --add hello example
------------------------------------------------
and you have now told git to track those two files.
you'll have to use the object name, not the filename of the object:
----------------
-$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
+$ git cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
----------------
where the `-t` tells `git-cat-file` to tell you what the "type" of the
regular file), and you can see the contents with
----------------
-$ git-cat-file "blob" 557db03
+$ git cat-file "blob" 557db03
----------------
which will print out "Hello World". The object `557db03` is nothing
`git-diff-files` command:
------------
-$ git-diff-files
+$ git diff-files
------------
Oops. That wasn't very readable. It just spit out its own internal
that it has noticed that "hello" has been modified, and that the old object
contents it had have been replaced with something else.
-To make it readable, we can tell git-diff-files to output the
+To make it readable, we can tell `git-diff-files` to output the
differences as a patch, using the `-p` flag:
------------
-$ git-diff-files -p
+$ git diff-files -p
diff --git a/hello b/hello
index 557db03..263414f 100644
--- a/hello
what is recorded in the index, and what is currently in the working
tree. That's very useful.
-A common shorthand for `git-diff-files -p` is to just write `git
+A common shorthand for `git diff-files -p` is to just write `git
diff`, which will do the same thing.
------------
tree was all about, along with information of how we came to that state.
Creating a tree object is trivial, and is done with `git-write-tree`.
-There are no options or other input: git-write-tree will take the
+There are no options or other input: `git write-tree` will take the
current index state, and write an object that describes that whole
index. In other words, we're now tying together all the different
filenames with their contents (and their permissions), and we're
creating the equivalent of a git "directory" object:
------------------------------------------------
-$ git-write-tree
+$ git write-tree
------------------------------------------------
and this will just output the name of the resulting tree, in this case
----------------
which is another incomprehensible object name. Again, if you want to,
-you can use `git-cat-file -t 8988d\...` to see that this time the object
+you can use `git cat-file -t 8988d\...` to see that this time the object
is not a "blob" object, but a "tree" object (you can also use
-`git-cat-file` to actually output the raw object contents, but you'll see
+`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
all with a sequence of simple shell commands:
------------------------------------------------
-$ tree=$(git-write-tree)
-$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
-$ git-update-ref HEAD $commit
+$ tree=$(git write-tree)
+$ commit=$(echo 'Initial commit' | git commit-tree $tree)
+$ git update-ref HEAD $commit
------------------------------------------------
In this case this creates a totally new commit that is not related to
state in the working tree, 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,
+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:
But now we can do
----------------
-$ git-diff-index -p HEAD
+$ git diff-index -p HEAD
----------------
(where `-p` has the same meaning as it did in `git-diff-files`), and it
working tree, but when given the `\--cached` flag, it is told to
instead compare against just the index cache contents, and ignore the
current working tree state entirely. Since we just wrote the index
-file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return
+file to HEAD, doing `git diff-index \--cached -p HEAD` should thus return
an empty set of differences, and that's exactly what it does.
[NOTE]
update the index cache:
------------------------------------------------
-$ git-update-index hello
+$ git update-index hello
------------------------------------------------
(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-\*` versions here. After
-we've updated `hello` in the index, `git-diff-files -p` now shows no
-differences, but `git-diff-index -p HEAD` still *does* show that the
+we've updated `hello` in the index, `git diff-files -p` now shows no
+differences, but `git diff-index -p HEAD` still *does* show that the
current state is different from the state we committed. In fact, now
`git-diff-index` shows the same difference whether we use the `--cached`
flag or not, since now the index is coherent with the working tree.
the same diff that we've already seen several times, we can now do
----------------
-$ git-diff-tree -p HEAD
+$ git diff-tree -p HEAD
----------------
(again, `-p` means to show the difference as a human-readable patch),
powerful)
----------------
-$ git-whatchanged -p
+$ git whatchanged -p
----------------
and you will see exactly what has changed in the repository over its
message, along with optionally a PGP signature that says that yes,
you really did
that tag. You create these annotated tags with either the `-a` or
-`-s` flag to `git tag`:
+`-s` flag to `git-tag`:
----------------
$ git tag -s <tagname>
history outside the project you created.
- if you want to move or duplicate a git repository, you can do so. There
- is `git clone` command, but if all you want to do is just to
+ 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`.
So after you do a `cp -a` to create a new copy, you'll want to do
+
----------------
-$ git-update-index --refresh
+$ git update-index --refresh
----------------
+
in the new repository to make sure that the index file is up-to-date.
so usually you'll precede the `git-update-index` with a
----------------
-$ git-read-tree --reset HEAD
-$ git-update-index --refresh
+$ git read-tree --reset HEAD
+$ git update-index --refresh
----------------
which will force a total index re-build from the tree pointed to by `HEAD`.
It resets the index contents to `HEAD`, and then the `git-update-index`
makes sure to match up all index entries with the checked-out files.
If the original repository had uncommitted changes in its
-working tree, `git-update-index --refresh` notices them and
+working tree, `git update-index --refresh` notices them and
tells you they need to be updated.
The above can also be written as simply
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
+`git-status` and `git-commit` are slightly more complex scripts around
the basic git commands.
Many (most?) public remote repositories will not contain any of
followed by
----------------
-$ git-read-tree HEAD
+$ git read-tree HEAD
----------------
to populate the index. However, now you have populated the index, and
those, you'd check them out with
----------------
-$ git-checkout-index -u -a
+$ git checkout-index -u -a
----------------
where the `-u` flag means that you want the checkout to keep the index
up-to-date (so that you don't have to refresh it afterward), and the
`-a` flag means "check out all files" (if you have a stale copy or an
older version of a checked out tree you may also need to add the `-f`
-flag first, to tell git-checkout-index to *force* overwriting of any old
+flag first, to tell `git-checkout-index` to *force* overwriting of any old
files).
Again, this can all be simplified with
================================================
If you make the decision to start your new branch at some
other point in the history than the current `HEAD`, you can do so by
-just telling `git checkout` what the base of the checkout would be.
+just telling `git-checkout` what the base of the checkout would be.
In other words, if you have an earlier tag or branch, you'd just do
------------
which will simply _create_ the branch, but will not do anything further.
You can then later -- once you decide that you want to actually develop
-on that branch -- switch to that branch with a regular `git checkout`
+on that branch -- switch to that branch with a regular `git-checkout`
with the branchname as the argument.
------------------------------------------------
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
+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
the index file so far when making the commit). The `-m` flag is to give the
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 merge`, which wants to know which branches you want
+script called `git-merge`, which wants to know which branches you want
to resolve and what the merge is all about:
------------
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.
+message about your adventures in `git-merge`-land.
After you're done, start up `gitk \--all` to see graphically what the
history looks like. Notice that `mybranch` still exists, and you can
environment, is `git show-branch`.
------------------------------------------------
-$ git-show-branch --topo-order --more=1 master mybranch
+$ git show-branch --topo-order --more=1 master mybranch
* [master] Merge work in mybranch
! [mybranch] Some work.
--
before the commit log message is a short name you can use to
name the commit. In the above example, 'master' and 'mybranch'
are branch heads. 'master^' is the first parent of 'master'
-branch head. Please see 'git-rev-parse' documentation if you
+branch head. Please see linkgit:git-rev-parse[1] if you want to
see more complex cases.
[NOTE]
-Without the '--more=1' option, 'git-show-branch' would not output the
+Without the '--more=1' option, `git-show-branch` would not output the
'[master^]' commit, as '[mybranch]' commit is a common ancestor of
-both 'master' and 'mybranch' tips. Please see 'git-show-branch'
-documentation for details.
+both 'master' and 'mybranch' tips. Please see linkgit:git-show-branch[1]
+for details.
[NOTE]
If there were more commits on the 'master' branch after the merge, the
-merge commit itself would not be shown by 'git-show-branch' by
+merge commit itself would not be shown by `git-show-branch` by
default. You would need to provide '--sparse' option to make the
merge commit visible in this case.
Now, let's pretend you are the one who did all the work in
`mybranch`, and the fruit of your hard work has finally been merged
to the `master` branch. Let's go back to `mybranch`, and run
-`git merge` to get the "upstream changes" back to your branch.
+`git-merge` to get the "upstream changes" back to your branch.
------------
$ git checkout mybranch
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 merge`. In fact, a remote merge ends up being nothing
+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"
-followed by a `git merge`.
+followed by a `git-merge`.
Fetching from a remote repository is done by, unsurprisingly,
-`git fetch`:
+`git-fetch`:
----------------
$ git fetch <remote-repository>
[NOTE]
You could do without using any branches at all, by
keeping as many local repositories as you would like to have
-branches, and merging between them with `git pull`, just like
+branches, and merging between them with `git-pull`, just like
you merge between branches. The advantage of this approach is
that it lets you keep a set of files for each `branch` checked
out and you may find it easier to switch back and forth if you
$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/
------------------------------------------------
-and use the "linus" keyword with `git pull` instead of the full URL.
+and use the "linus" keyword with `git-pull` instead of the full URL.
Examples.
+* [master^] Some fun.
------------
-Remember, before running `git merge`, our `master` head was at
+Remember, before running `git-merge`, our `master` head was at
"Some fun." commit, while our `mybranch` head was at "Some
work." commit.
The command it uses is `git-merge-base`:
------------
-$ mb=$(git-merge-base HEAD mybranch)
+$ mb=$(git merge-base HEAD mybranch)
------------
The command writes the commit object name of the common ancestor
tell it by:
------------
-$ git-name-rev $mb
+$ git name-rev $mb
my-first-tag
------------
this:
------------
-$ git-read-tree -m -u $mb HEAD mybranch
+$ git read-tree -m -u $mb HEAD mybranch
------------
This is the same `git-read-tree` command we have already seen,
inspect the index file with this command:
------------
-$ git-ls-files --stage
+$ git ls-files --stage
100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
To look at only non-zero stages, use `\--unmerged` flag:
------------
-$ git-ls-files --unmerged
+$ git ls-files --unmerged
100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello
`git-merge-index` command:
------------
-$ git-merge-index git-merge-one-file hello
+$ git merge-index git-merge-one-file hello
Auto-merging hello.
merge: warning: conflicts during merge
ERROR: Merge conflict in hello.
--stage` again at this point:
------------
-$ git-ls-files --stage
+$ git ls-files --stage
100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example
100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello
100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello
------------
This is the state of the index file and the working file after
-`git merge` returns control back to you, leaving the conflicting
+`git-merge` returns control back to you, leaving the conflicting
merge for you to resolve. Notice that the path `hello` is still
-unmerged, and what you see with `git diff` at this point is
+unmerged, and what you see with `git-diff` at this point is
differences since stage 2 (i.e. your version).
done only once.
[NOTE]
-`git push` uses a pair of programs,
+`git-push` uses a pair of programs,
`git-send-pack` on your local machine, and `git-receive-pack`
on the remote machine. The communication between the two over
the network internally uses an SSH connection.
------------
Then, make that directory into a git repository by running
-`git init`, but this time, since its name is not the usual
+`git-init`, but this time, since its name is not the usual
`.git`, we do things slightly differently:
------------
-$ GIT_DIR=my-git.git git-init
+$ GIT_DIR=my-git.git git init
------------
Make sure this directory is available for others you want your
If you plan to publish this repository to be accessed over http,
you should do `chmod +x my-git.git/hooks/post-update` at this
point. This makes sure that every time you push into this
-repository, `git-update-server-info` is run.
+repository, `git update-server-info` is run.
Your "public repository" is now ready to accept your changes.
Come back to the machine you have your private repository. From
will do it for you. If you followed the tutorial examples, you
would have accumulated about 17 objects in `.git/objects/??/`
-directories by now. `git repack` tells you how many objects it
+directories by now. `git-repack` tells you how many objects it
packed, and stores the packed file in `.git/objects/pack`
directory.
3. Push into the public repository from your primary
repository.
-4. `git repack` the public repository. This establishes a big
+4. `git-repack` the public repository. This establishes a big
pack that contains the initial set of objects as the
- baseline, and possibly `git prune` if the transport
+ baseline, and possibly `git-prune` if the transport
used for pulling from your repository supports packed
repositories.
6. Push your changes to the public repository, and announce it
to the public.
-7. Every once in a while, "git repack" the public repository.
+7. Every once in a while, "git-repack" the public repository.
Go back to step 5. and continue working.
A recommended work cycle for a "subsystem maintainer" who works
on that project and has an own "public repository" goes like this:
-1. Prepare your work repository, by `git clone` the public
+1. Prepare your work repository, by `git-clone` the public
repository of the "project lead". The URL used for the
initial cloning is stored in the remote.origin.url
configuration variable.
point at the repository you are borrowing from.
4. Push into the public repository from your primary
- repository. Run `git repack`, and possibly `git prune` if the
+ repository. Run `git-repack`, and possibly `git-prune` if the
transport used for pulling from your repository supports
packed repositories.
"project lead" and possibly your "sub-subsystem
maintainers" to pull from it.
-7. Every once in a while, `git repack` the public repository.
+7. Every once in a while, `git-repack` the public repository.
Go back to step 5. and continue working.
not have a "public" repository is somewhat different. It goes
like this:
-1. Prepare your work repository, by `git clone` the public
+1. Prepare your work repository, by `git-clone` the public
repository of the "project lead" (or a "subsystem
maintainer", if you work on a subsystem). The URL used for
the initial cloning is stored in the remote.origin.url
have to worry. git supports "shared public repository" style of
cooperation you are probably more familiar with as well.
-See linkgit:gitcvs-migration[7][git for CVS users] for the details.
+See linkgit:gitcvs-migration[7] for the details.
Bundling your work together
---------------------------
------------
You can make sure 'git show-branch' matches the state before
-those two 'git merge' you just did. Then, instead of running
-two 'git merge' commands in a row, you would merge these two
+those two 'git-merge' you just did. Then, instead of running
+two 'git-merge' commands in a row, you would merge these two
branch heads (this is known as 'making an Octopus'):
------------
GIT
---
-Part of the linkgit:git[7] suite.
+Part of the linkgit:git[1] suite.