X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fcore-tutorial.txt;h=99817c53375e6f58b7a3e089cd81e3af5aaffc79;hb=620bb245b945531bb6e08016d5f28caf9e797786;hp=4fb6f4143cd849fc81f3ee5d2b8e4ee77e21137d;hpb=d60a6a662fac58f833efde93c962314fd5d83541;p=git.git diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 4fb6f4143..99817c533 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -4,34 +4,24 @@ A git core tutorial for developers Introduction ------------ -This is trying to be a short tutorial on setting up and using a git -repository, mainly because being hands-on and using explicit examples is -often the best way of explaining what is going on. +This tutorial explains how to use the "core" git programs to set up and +work with a git repository. -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. +If you just need to use git as a revision control system you may prefer +to start with link:tutorial.html[a tutorial introduction to git] 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. 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. -The material presented here often goes deep describing how things -work internally. If you are mostly interested in using git as a -SCM, you can skip them during your first pass. - [NOTE] -And those "too deep" descriptions are often marked as Note. - -[NOTE] -If you are already familiar with another version control system, -like CVS, you may want to take a look at -link:everyday.html[Everyday GIT in 20 commands or so] first -before reading this. +Deeper technical details are often marked as Notes, which you can +skip on your first reading. Creating a git repository @@ -563,13 +553,8 @@ can explore on your own. [NOTE] Most likely, you are not directly using the core -git Plumbing commands, but using Porcelain like Cogito on top -of it. Cogito works a bit differently and you usually do not -have to run `git-update-index` yourself for changed files (you -do tell underlying git about additions and removals via -`cg-add` and `cg-rm` commands). Just before you make a commit -with `cg-commit`, Cogito figures out which files you modified, -and runs `git-update-index` on them for you. +git Plumbing commands, but using Porcelain such as `git-add`, `git-rm' +and `git-commit'. Tagging a version @@ -696,8 +681,8 @@ $ git reset 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` is the -above two lines implemented in `git-reset`, but some things like +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. @@ -815,8 +800,8 @@ you have, you can say $ git branch ------------ -which is nothing more than a simple script around `ls .git/refs/heads`. -There will be asterisk in front of the branch you are currently on. +which used to be nothing more than a simple script around `ls .git/refs/heads`. +There will be an asterisk in front of the branch you are currently on. Sometimes you may wish to create a new branch _without_ actually checking it out and switching to it. If so, just use the command @@ -843,7 +828,7 @@ that branch, and do some work there. ------------------------------------------------ $ git checkout mybranch $ echo "Work, work, work" >>hello -$ git commit -m 'Some work.' -i hello +$ git commit -m "Some work." -i hello ------------------------------------------------ Here, we just added another line to `hello`, and we used a shorthand for @@ -868,7 +853,7 @@ hasn't happened in the `master` branch at all. Then do ------------ $ echo "Play, play, play" >>hello $ echo "Lots of fun" >>example -$ git commit -m 'Some fun.' -i hello example +$ git commit -m "Some fun." -i hello example ------------ since the master branch is obviously in a much better mood. @@ -893,7 +878,7 @@ script called `git merge`, which wants to know which branches you want to resolve and what the merge is all about: ------------ -$ git merge "Merge work in mybranch" HEAD mybranch +$ git merge -m "Merge work in mybranch" mybranch ------------ where the first argument is going to be used as the commit message if @@ -962,7 +947,7 @@ the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` branch. Three commits are shown along with their log messages. All of them have non blank characters in the first column (`*` -shows an ordinary commit on the current branch, `.` is a merge commit), which +shows an ordinary commit on the current branch, `-` is a merge commit), which means they are now part of the `master` branch. Only the "Some work" commit has the plus `+` character in the second column, because `mybranch` has not been merged to incorporate these @@ -980,7 +965,7 @@ to the `master` branch. Let's go back to `mybranch`, and run ------------ $ git checkout mybranch -$ git merge "Merge upstream changes." HEAD master +$ git merge -m "Merge upstream changes." master ------------ This outputs something like this (the actual commit object names @@ -1096,7 +1081,7 @@ to help dumb transport downloaders. 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, -and not used by `git pull` or `git push` scripts. +and are not used by `git pull` or `git push` scripts. Once you fetch from the remote repository, you `merge` that with your current branch. @@ -1203,7 +1188,7 @@ $ mb=$(git-merge-base HEAD mybranch) The command writes the commit object name of the common ancestor to the standard output, so we captured its output to a variable, -because we will be using it in the next step. BTW, the common +because we will be using it in the next step. By the way, the common ancestor commit is the "New day." commit in this case. You can tell it by: @@ -1469,7 +1454,7 @@ 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://tinyurl.com/a2jdg[Randy Dunlap's presentation]. +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 @@ -1622,8 +1607,8 @@ in both of them. You could merge in 'diff-fix' first and then 'commit-fix' next, like this: ------------ -$ git merge 'Merge fix in diff-fix' master diff-fix -$ git merge 'Merge fix in commit-fix' master commit-fix +$ git merge -m "Merge fix in diff-fix" diff-fix +$ git merge -m "Merge fix in commit-fix" commit-fix ------------ Which would result in: @@ -1686,5 +1671,3 @@ merge two at a time, documenting how you resolved the conflicts, and the reason why you preferred changes made in one side over the other. Otherwise it would make the project history harder to follow, not easier. - -[ to be continued.. cvsimports ]