X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Ftutorial.txt;h=214673db06914c49c25038c4c70ac76c90dbeff5;hb=0772b9a6331357913417722eab672f8b5aa69e50;hp=00f4bab954f9d40000593bdfa04145ca5504b680;hpb=2ae6c706749b44f05917fcd04037f545d16fb345;p=git.git diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 00f4bab9..214673db 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -1,6 +1,5 @@ A short git tutorial ==================== -v0.99.5, Aug 2005 Introduction ------------ @@ -163,7 +162,7 @@ you'll have to use the object name, not the filename of the object: git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 where the `-t` tells `git-cat-file` to tell you what the "type" of the -object is. Git will tell you that you have a "blob" object (ie just a +object is. git will tell you that you have a "blob" object (ie just a regular file), and you can see the contents with git-cat-file "blob" 557db03 @@ -293,14 +292,16 @@ also wants to get a commit message on its standard input, and it will write out the resulting object name for the commit to its standard output. -And this is where we create the `.git/refs/heads/master` file. This 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: +And this is where we create the `.git/refs/heads/master` file +which is pointed at by `HEAD`. This file is supposed to contain +the reference to the top-of-tree of the master branch, and since +that's exactly what `git-commit-tree` spits out, we can do this +all with a sequence of simple shell commands: ------------------------------------------------ -echo "Initial commit" | \ - git-commit-tree $(git-write-tree) > .git/refs/heads/master +tree=$(git-write-tree) +commit=$(echo 'Initial commit' | git-commit-tree $tree) +git-update-ref HEAD $(commit) ------------------------------------------------ which will say: @@ -382,7 +383,7 @@ come from the working tree or not. This is not hard to understand, as soon as you realize that git simply never knows (or cares) about files that it is not told about -explicitly. Git will never go *looking* for files to compare, it +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. ================ @@ -454,6 +455,41 @@ the same diff that we've already seen several times, we can now do (again, `-p` means to show the difference as a human-readable patch), and it will show what the last commit (in `HEAD`) actually changed. +[NOTE] +============ +Here is an ASCII art by Jon Loeliger that illustrates how +various diff-\* commands compare things. + + diff-tree + +----+ + | | + | | + V V + +-----------+ + | Object DB | + | Backing | + | Store | + +-----------+ + ^ ^ + | | + | | diff-index --cached + | | + diff-index | V + | +-----------+ + | | Index | + | | "cache" | + | +-----------+ + | ^ + | | + | | diff-files + | | + V V + +-----------+ + | Working | + | Directory | + +-----------+ +============ + 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. @@ -548,7 +584,7 @@ name for the state at that point. Copying repositories -------------------- -Git repositories are normally totally self-sufficient, and it's worth noting +git repositories are normally totally self-sufficient, and it's worth noting that unlike CVS, for example, there is no separate notion of "repository" and "working tree". A git repository normally *is* the working tree, with the local git information hidden in the `.git` @@ -972,7 +1008,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 @@ -993,13 +1029,13 @@ necessary objects. Because of this behaviour, 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 would suffice. + There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload` programs, which are 'commit walkers'; they outlived their -usefulness when GIT Native and SSH transports were introduced, +usefulness when git Native and SSH transports were introduced, and not used by `git pull` or `git push` scripts. Once you fetch from the remote repository, you `resolve` that @@ -1027,7 +1063,9 @@ multiple working trees, but disk space is cheap these days. [NOTE] You could even pull from your own repository by -giving '.' as parameter to `git pull`. +giving '.' as parameter to `git pull`. This +is useful when you want to merge a local branch (or more, if you +are making an Octopus) into the current branch. It is likely that you will be pulling from the same remote repository from time to time. As a short hand, you can store @@ -1103,7 +1141,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. `.git`. Let's create such a public repository for project `my-git`. After logging into the remote machine, create @@ -1113,7 +1151,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-db`, but this time, since its name is not the usual `.git`, we do things slightly differently: