X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Ftutorial.txt;h=129c5c5f5b8657175db7efed2c06078affd05ab6;hb=732bcf942c6e99879349711fd29b5062a704e248;hp=554ee0af912368cb842d93c025e742daaf47f5f2;hpb=75c3a5ccdf114b5485e4828db1923bf4a35b19e2;p=git.git diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 554ee0af9..129c5c5f5 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -11,6 +11,16 @@ diff" with: $ man git-diff ------------------------------------------------ +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: + +------------------------------------------------ +$ git config --global user.name "Your Name Comes Here" +$ git config --global user.email you@yourdomain.example.com +------------------------------------------------ + + Importing a new project ----------------------- @@ -20,18 +30,18 @@ can place it under git revision control as follows. ------------------------------------------------ $ tar xzf project.tar.gz $ cd project -$ git init-db +$ git init ------------------------------------------------ Git will reply ------------------------------------------------ -defaulting to local storage area +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 with +every file under the current directory (note the '.') with: ------------------------------------------------ $ git add . @@ -40,42 +50,90 @@ $ git add . Finally, ------------------------------------------------ -$ git commit -a +$ git commit ------------------------------------------------ will prompt you for a commit message, then record the current state of all the files to the repository. +Making changes +-------------- + Try modifying some files, then run ------------------------------------------------ $ git diff ------------------------------------------------ -to review your changes. When you're done, +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: + +------------------------------------------------ +$ 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. + +Alternatively, instead of running `git add` beforehand, you can use ------------------------------------------------ $ git commit -a ------------------------------------------------ -will again prompt your for a message describing the change, and then -record the new versions of the modified files. +which will automatically notice modified (but not new) files. 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) line summarizing the change, followed by a blank line and then a more thorough description. Tools that turn commits into email, for -example, use the first line on the Subject line and the rest of the +example, use the first line on the Subject: line and the rest of the commit in the body. -To add a new file, first create the file, then ------------------------------------------------- -$ git add path/to/new/file ------------------------------------------------- +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 ...' + +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 -then commit as usual. No special command is required when removing a -file; just remove it, then commit. +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 +--------------------- At any point you can view the history of your changes using @@ -89,6 +147,13 @@ If you also want to see complete diffs at each step, use $ git log -p ------------------------------------------------ +Often the overview of the change is useful to get a feel of +each step + +------------------------------------------------ +$ git log --stat --summary +------------------------------------------------ + Managing branches ----------------- @@ -141,10 +206,10 @@ $ git commit -a ------------------------------------------------ at this point the two branches have diverged, with different changes -made in each. To merge the changes made in the two branches, run +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, @@ -169,6 +234,15 @@ $ gitk will show a nice graphical representation of the resulting history. +At this point you could delete the experimental branch with + +------------------------------------------------ +$ git branch -d experimental +------------------------------------------------ + +This command ensures that the changes in the experimental branch are +already in the current branch. + If you develop on a branch crazy-idea, then regret it, you can always delete the branch with @@ -209,47 +283,63 @@ at /home/bob/myrepo. She does this with: ------------------------------------------------ $ cd /home/alice/project -$ git pull /home/bob/myrepo +$ git pull /home/bob/myrepo master ------------------------------------------------ -This actually pulls changes from the branch in Bob's repository named -"master". Alice could request a different branch by adding the name -of the branch to the end of the git pull command line. +This merges the changes from Bob's "master" branch into Alice's +current branch. If Alice has made her own changes in the meantime, +then she may need to manually fix any conflicts. (Note that the +"master" argument in the above command is actually unnecessary, as it +is the default.) + +The "pull" command thus performs two operations: it fetches changes +from a remote branch, then merges them into the current branch. -This merges Bob's changes into her repository; "git log" will -now show the new commits. If Alice has made her own changes in the -meantime, then Bob's changes will be merged in, and she will need to -manually fix any conflicts. +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 +------------------------------------------------ -A more cautious Alice might wish to examine Bob's changes before -pulling them. She can do this by creating a temporary branch just -for the purpose of studying Bob's changes: +With this, you 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. (Unlike git pull, git fetch just fetches a copy -of Bob's line of development without doing any merging). 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 can -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 +------------------------------------- + +This `merge` can also be done by 'pulling from her own remote +tracking branch', like this: + +------------------------------------- +$ git pull . remotes/bob/master ------------------------------------- -The last command is a pull from the "bob-incoming" branch in Alice's -own repository. +Note that git pull always merges into the current branch, +regardless of what else is given on the commandline. Later, Bob can update his repo with Alice's latest changes using @@ -259,20 +349,25 @@ $ git pull Note that he doesn't need to give the path to Alice's repository; when Bob cloned Alice's repository, git stored the location of her -repository in the file .git/remotes/origin, and that location is used -as the default for pulls. - -Bob may also notice a branch in his repository that he didn't create: +repository in the repository configuration, and that location is +used for pulls: ------------------------------------- -$ git branch -* master - origin +$ git config --get remote.origin.url +/home/bob/myrepo ------------------------------------- -The "origin" branch, which was created automatically by "git clone", -is a pristine copy of Alice's master branch; Bob should never commit -to it. +(The complete configuration created by git-clone is visible using +"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 +name "origin/master": + +------------------------------------- +$ git branch -r + origin/master +------------------------------------- If Bob later decides to work from a different host, he can still perform clones and pulls using the ssh protocol: @@ -312,7 +407,7 @@ commit. $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 ------------------------------------- -But there other ways to refer to commits. You can use any initial +But there are other ways to refer to commits. You can use any initial part of the name that is long enough to uniquely identify the commit: ------------------------------------- @@ -322,8 +417,8 @@ $ git show HEAD # the tip of the current branch $ git show experimental # the tip of the "experimental" branch ------------------------------------- -Every commit has at least one "parent" commit, which points to the -previous state of the project: +Every commit usually has one "parent" commit +which points to the previous state of the project: ------------------------------------- $ git show HEAD^ # to see the parent of HEAD @@ -363,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 @@ -441,10 +538,10 @@ of the file: $ git diff v2.5:Makefile HEAD:Makefile.in ------------------------------------- -You can also use "git cat-file -p" to see any such file: +You can also use "git show" to see any such file: ------------------------------------- -$ git cat-file -p v2.5:Makefile +$ git show v2.5:Makefile ------------------------------------- Next Steps