X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Ftutorial.txt;h=fff1068c54e313efd4fb16a330c24d4749bc7712;hb=08e1812db1585c450bfe7f41e7106222346c88da;hp=d2bf0b905aa3f2b67f781310b9f60c05fa948c67;hpb=c326246accf36bc070b326773df2b9ec1c336037;p=git.git diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index d2bf0b905..fff1068c5 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -1,9 +1,13 @@ -A tutorial introduction to git -============================== +A tutorial introduction to git (for version 1.5.1 or newer) +=========================================================== This tutorial explains how to import a new project into git, make changes to it, and share changes with other developers. +If you are instead primarily interested in using git to fetch a project, +for example, to test the latest version, you may prefer to start with +the first two chapters of link:user-manual.html[The Git User's Manual]. + First, note that you can get documentation for a command such as "git diff" with: @@ -11,15 +15,13 @@ diff" with: $ man git-diff ------------------------------------------------ -It is a good idea to introduce yourself to git before doing any -operation. The easiest way to do so is: +It is a good idea to introduce yourself to git with your name and +public email address before doing any operation. The easiest +way to do so is: ------------------------------------------------ -$ cat >~/.gitconfig <<\EOF -[user] - name = Your Name Comes Here - email = you@yourdomain.example.com -EOF +$ git config --global user.name "Your Name Comes Here" +$ git config --global user.email you@yourdomain.example.com ------------------------------------------------ @@ -42,42 +44,67 @@ Initialized empty Git repository in .git/ ------------------------------------------------ You've now initialized the working directory--you may notice a new -directory created, named ".git". Tell git that you want it to track -every file under the current directory (note the '.') with: +directory created, named ".git". + +Next, tell git to take a snapshot of the contents of all files under the +current directory (note the '.'), with gitlink:git-add[1]: ------------------------------------------------ $ git add . ------------------------------------------------ -Finally, +This snapshot is now stored in a temporary staging area which git calls +the "index". You can permanently store the contents of the index in the +repository with gitlink:git-commit[1]: ------------------------------------------------ $ git commit ------------------------------------------------ -will prompt you for a commit message, then record the current state -of all the files to the repository. +This will prompt you for a commit message. You've now stored the first +version of your project in git. Making changes -------------- -Try modifying some files, then run +Modify some files, then add their updated contents to the index: ------------------------------------------------ -$ git diff +$ git add file1 file2 file3 ------------------------------------------------ -to review your changes. When you're done, tell git that you -want the updated contents of these files in the commit and then -make a commit, like this: +You are now ready to commit. You can see what is about to be committed +using gitlink:git-diff[1] with the --cached option: + +------------------------------------------------ +$ git diff --cached +------------------------------------------------ + +(Without --cached, gitlink:git-diff[1] will show you any changes that +you've made but not yet added to the index.) You can also get a brief +summary of the situation with gitlink:git-status[1]: + +------------------------------------------------ +$ git status +# On branch master +# Changes to be committed: +# (use "git reset HEAD ..." to unstage) +# +# modified: file1 +# modified: file2 +# modified: file3 +# +------------------------------------------------ + +If you need to make any further adjustments, do so now, and then add any +newly modified content to the index. Finally, commit your changes with: ------------------------------------------------ -$ git add file1 file2 file3 $ git commit ------------------------------------------------ This will again prompt your for a message describing the change, and then -record the new versions of the files you listed. +record a new version of the project. Alternatively, instead of running `git add` beforehand, you can use @@ -85,7 +112,8 @@ Alternatively, instead of running `git add` beforehand, you can use $ git commit -a ------------------------------------------------ -which will automatically notice modified (but not new) files. +which will automatically notice any modified (but not new) files, add +them to the index, and commit, all in one step. A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) @@ -94,48 +122,18 @@ thorough description. Tools that turn commits into email, for example, use the first line on the Subject: line and the rest of the commit in the body. - Git tracks content not files ---------------------------- -With git you have to explicitly "add" all the changed _content_ you -want to commit together. This can be done in a few different ways: - -1) By using 'git add ...' +Many revision control systems provide an "add" command that tells the +system to start tracking changes to a new file. Git's "add" command +does something simpler and more powerful: `git add` is used both for new +and newly modified files, and in both cases it takes a snapshot of the +given files and stages that content in the index, ready for inclusion in +the next commit. - This can be performed multiple times before a commit. Note that this - is not only for adding new files. Even modified files must be - added to the set of changes about to be committed. The "git status" - command gives you a summary of what is included so far for the - next commit. When done you should use the 'git commit' command to - make it real. - - Note: don't forget to 'add' a file again if you modified it after the - first 'add' and before 'commit'. Otherwise only the previous added - state of that file will be committed. This is because git tracks - content, so what you're really 'add'ing to the commit is the *content* - of the file in the state it is in when you 'add' it. - -2) By using 'git commit -a' directly - - This is a quick way to automatically 'add' the content from all files - that were modified since the previous commit, and perform the actual - commit without having to separately 'add' them beforehand. This will - not add content from new files i.e. files that were never added before. - Those files still have to be added explicitly before performing a - commit. - -But here's a twist. If you do 'git commit ...' then only -the changes belonging to those explicitly specified files will be -committed, entirely bypassing the current "added" changes. Those "added" -changes will still remain available for a subsequent commit though. - -However, for normal usage you only have to remember 'git add' + 'git commit' -and/or 'git commit -a'. - - -Viewing the changelog ---------------------- +Viewing project history +----------------------- At any point you can view the history of your changes using @@ -211,7 +209,7 @@ at this point the two branches have diverged, with different changes made in each. To merge the changes made in experimental into master, run ------------------------------------------------ -$ git pull . experimental +$ git merge experimental ------------------------------------------------ If the changes don't conflict, you're done. If there are conflicts, @@ -297,46 +295,51 @@ is the default.) The "pull" command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch. -You can perform the first operation alone using the "git fetch" -command. For example, Alice could create a temporary branch just to -track Bob's changes, without merging them with her own, using: +When you are working in a small closely knit group, it is not +unusual to interact with the same repository over and over +again. By defining 'remote' repository shorthand, you can make +it easier: + +------------------------------------------------ +$ git remote add bob /home/bob/myrepo +------------------------------------------------ + +With this, Alice can perform the first operation alone using the +"git fetch" command without merging them with her own branch, +using: ------------------------------------- -$ git fetch /home/bob/myrepo master:bob-incoming +$ git fetch bob ------------------------------------- -which fetches the changes from Bob's master branch into a new branch -named bob-incoming. Then +Unlike the longhand form, when Alice fetches from Bob using a +remote repository shorthand set up with `git remote`, what was +fetched is stored in a remote tracking branch, in this case +`bob/master`. So after this: ------------------------------------- -$ git log -p master..bob-incoming +$ git log -p master..bob/master ------------------------------------- shows a list of all the changes that Bob made since he branched from Alice's master branch. -After examining those changes, and possibly fixing things, Alice -could pull the changes into her master branch: +After examining those changes, Alice +could merge the changes into her master branch: ------------------------------------- -$ git checkout master -$ git pull . bob-incoming +$ git merge bob/master ------------------------------------- -The last command is a pull from the "bob-incoming" branch in Alice's -own repository. - -Alice could also perform both steps at once with: +This `merge` can also be done by 'pulling from her own remote +tracking branch', like this: ------------------------------------- -$ git pull /home/bob/myrepo master:bob-incoming +$ git pull . remotes/bob/master ------------------------------------- -This is just like the "git pull /home/bob/myrepo master" that we saw -before, except that it also stores the unmerged changes from bob's -master branch in bob-incoming before merging them into Alice's -current branch. Note that git pull always merges into the current -branch, regardless of what else is given on the commandline. +Note that git pull always merges into the current branch, +regardless of what else is given on the command line. Later, Bob can update his repo with Alice's latest changes using @@ -350,12 +353,12 @@ repository in the repository configuration, and that location is used for pulls: ------------------------------------- -$ git repo-config --get remote.origin.url -/home/bob/myrepo +$ git config --get remote.origin.url +/home/alice/project ------------------------------------- (The complete configuration created by git-clone is visible using -"git repo-config -l", and the gitlink:git-repo-config[1] man page +"git config -l", and the gitlink:git-config[1] man page explains the meaning of each option.) Git also keeps a pristine copy of Alice's master branch under the @@ -455,9 +458,11 @@ $ git reset --hard HEAD^ # reset your current branch and working Be careful with that last command: in addition to losing any changes in the working directory, it will also remove all later commits from this branch. If this branch is the only branch containing those -commits, they will be lost. (Also, don't use "git reset" on a -publicly-visible branch that other developers pull from, as git will -be confused by history that disappears in this way.) +commits, they will be lost. Also, don't use "git reset" on a +publicly-visible branch that other developers pull from, as it will +force needless merges on other developers to clean up the history. +If you need to undo changes that you have pushed, use gitlink:git-revert[1] +instead. The git grep command can search for strings in any version of your project, so @@ -559,7 +564,7 @@ link:tutorial-2.html[Part two of this tutorial] explains the object database, the index file, and a few other odds and ends that you'll need to make the most of git. -If you don't want to consider with that right away, a few other +If you don't want to continue with that right away, a few other digressions that may be interesting at this point are: * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert