diff options
author | Junio C Hamano <junio@hera.kernel.org> | 2008-07-02 03:06:38 +0000 |
---|---|---|
committer | Junio C Hamano <junio@hera.kernel.org> | 2008-07-02 03:06:38 +0000 |
commit | fce7c7e1549d1a2a2b0faf5952378236eed4d468 (patch) | |
tree | ffce2ae419b52786a0e567f4fddaadd89016f62c /gitcore-tutorial.txt | |
parent | bb8e996adf4293a0b624fe77e95e12ae8d1faed9 (diff) | |
download | git-htmldocs-fce7c7e1549d1a2a2b0faf5952378236eed4d468.tar.gz |
Autogenerated HTML docs for v1.5.6.1-156-ge903b
Diffstat (limited to 'gitcore-tutorial.txt')
-rw-r--r-- | gitcore-tutorial.txt | 127 |
1 files changed, 63 insertions, 64 deletions
diff --git a/gitcore-tutorial.txt b/gitcore-tutorial.txt index cb4ec4044..7d721c5b0 100644 --- a/gitcore-tutorial.txt +++ b/gitcore-tutorial.txt @@ -16,8 +16,8 @@ This tutorial explains how to use the "core" git programs 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 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. @@ -49,7 +49,7 @@ subdirectory, and initialize the git infrastructure with `git-init`: ------------------------------------------------ $ mkdir git-tutorial $ cd git-tutorial -$ git-init +$ git init ------------------------------------------------ to which git will reply @@ -108,8 +108,7 @@ references in these `refs` subdirectories when you actually start populating your tree. [NOTE] -An advanced user may want to take a look at the -linkgit:gitrepository-layout[5][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 @@ -150,7 +149,7 @@ adding a new entry with the `\--add` flag (or removing an entry with the 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. @@ -178,7 +177,7 @@ 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: ---------------- -$ 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 @@ -186,7 +185,7 @@ 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 ---------------- -$ git-cat-file "blob" 557db03 +$ git cat-file "blob" 557db03 ---------------- which will print out "Hello World". The object `557db03` is nothing @@ -232,7 +231,7 @@ git what has changed in the tree compared to your old index, using the `git-diff-files` command: ------------ -$ git-diff-files +$ git diff-files ------------ Oops. That wasn't very readable. It just spit out its own internal @@ -240,11 +239,11 @@ version of a `diff`, but that internal version really just tells you 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 @@ -260,7 +259,7 @@ 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. -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. ------------ @@ -285,14 +284,14 @@ 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. 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 @@ -303,9 +302,9 @@ 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 @@ -328,9 +327,9 @@ that's exactly what `git-commit-tree` spits out, we can do this 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 @@ -357,7 +356,7 @@ that on purpose, to show the difference between the index state, and the 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: @@ -373,7 +372,7 @@ didn't have anything to diff against. 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 @@ -395,7 +394,7 @@ In other words, `git-diff-index` normally compares a tree against the 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] @@ -423,15 +422,15 @@ work through the index file, so the first thing we need to do is to 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. @@ -478,7 +477,7 @@ of that commit itself, and show the difference directly. Thus, to get the same diff that we've already seen several times, we can now do ---------------- -$ git-diff-tree -p HEAD +$ git diff-tree -p HEAD ---------------- (again, `-p` means to show the difference as a human-readable patch), @@ -543,7 +542,7 @@ with the associated patches use the more complex (and much more powerful) ---------------- -$ git-whatchanged -p +$ git whatchanged -p ---------------- and you will see exactly what has changed in the repository over its @@ -654,7 +653,7 @@ information for the files involved) will likely need to be refreshed. So after you do a `cp -a` to create a new copy, you'll want to do + ---------------- -$ git-update-index --refresh +$ git update-index --refresh ---------------- + in the new repository to make sure that the index file is up-to-date. @@ -670,15 +669,15 @@ known state (you don't know *what* they've done and not yet checked in), 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 @@ -691,7 +690,7 @@ 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 +`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 @@ -714,7 +713,7 @@ $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git followed by ---------------- -$ git-read-tree HEAD +$ git read-tree HEAD ---------------- to populate the index. However, now you have populated the index, and @@ -723,14 +722,14 @@ actually have any of the working tree files to work on. To get 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 @@ -840,7 +839,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 +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 @@ -926,7 +925,7 @@ $ git commit -i hello 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 @@ -939,7 +938,7 @@ Another useful tool, especially if you do not always work in X-Window 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. -- @@ -964,25 +963,25 @@ commits from the master branch. The string inside brackets 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 @@ -1199,7 +1198,7 @@ algorithm. First, it finds the common ancestor between them. 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 @@ -1209,7 +1208,7 @@ ancestor commit is the "New day." commit in this case. You can tell it by: ------------ -$ git-name-rev $mb +$ git name-rev $mb my-first-tag ------------ @@ -1217,7 +1216,7 @@ After finding out a common ancestor commit, the second step is 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, @@ -1236,7 +1235,7 @@ trees are left in non-zero stages. At this point, you can 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 @@ -1253,7 +1252,7 @@ stages. 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 @@ -1265,7 +1264,7 @@ file, using 3-way merge. This is done by giving `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. @@ -1283,7 +1282,7 @@ the working tree.. This can be seen if you run `ls-files --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 @@ -1291,9 +1290,9 @@ $ git-ls-files --stage ------------ 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). @@ -1330,7 +1329,7 @@ into it later. Obviously, this repository creation needs to be 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. @@ -1350,7 +1349,7 @@ Then, make that directory into a git repository by running `.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 @@ -1369,7 +1368,7 @@ your login shell is `bash`, only `.bashrc` is read and not 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 @@ -1496,9 +1495,9 @@ keeps the necessary files up-to-date. 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. @@ -1512,14 +1511,14 @@ You can repack this private repository whenever you feel like. 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. @@ -1534,7 +1533,7 @@ on that project and has an own "public repository" goes like this: 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. @@ -1551,7 +1550,7 @@ like. "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. @@ -1559,7 +1558,7 @@ A recommended work cycle for an "individual developer" who does 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 @@ -1589,7 +1588,7 @@ suggested in the previous section may be new to you. You do not 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 --------------------------- |