diff options
Diffstat (limited to 'Documentation/gittutorial.txt')
| -rw-r--r-- | Documentation/gittutorial.txt | 114 |
1 files changed, 77 insertions, 37 deletions
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 48d1454..dee0505 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -7,6 +7,7 @@ gittutorial - A tutorial introduction to git (for version 1.5.1 or newer) SYNOPSIS -------- +[verse] git * DESCRIPTION @@ -26,6 +27,15 @@ First, note that you can get documentation for a command such as $ man git-log ------------------------------------------------ +or: + +------------------------------------------------ +$ git help log +------------------------------------------------ + +With the latter, you can use the manual viewer of your choice; see +linkgit:git-help[1] for more information. + 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: @@ -58,7 +68,7 @@ You've now initialized the working directory--you may notice a new directory created, named ".git". Next, tell git to take a snapshot of the contents of all files under the -current directory (note the '.'), with 'git-add': +current directory (note the '.'), with 'git add': ------------------------------------------------ $ git add . @@ -66,7 +76,7 @@ $ git add . 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 'git-commit': +repository with 'git commit': ------------------------------------------------ $ git commit @@ -85,15 +95,15 @@ $ git add file1 file2 file3 ------------------------------------------------ You are now ready to commit. You can see what is about to be committed -using 'git-diff' with the --cached option: +using 'git diff' with the --cached option: ------------------------------------------------ $ git diff --cached ------------------------------------------------ -(Without --cached, 'git-diff' will show you any changes that +(Without --cached, 'git diff' 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 'git-status': +summary of the situation with 'git status': ------------------------------------------------ $ git status @@ -117,7 +127,7 @@ $ git commit This will again prompt you for a message describing the change, and then record a new version of the project. -Alternatively, instead of running 'git-add' beforehand, you can use +Alternatively, instead of running 'git add' beforehand, you can use ------------------------------------------------ $ git commit -a @@ -138,7 +148,7 @@ Git tracks content not files 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 +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. @@ -299,9 +309,7 @@ alice$ git pull /home/bob/myrepo master 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.) +then she may need to manually fix any conflicts. The "pull" command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch. @@ -321,10 +329,37 @@ pulling, like this: ------------------------------------------------ alice$ git fetch /home/bob/myrepo master -alice$ git log -p ..FETCH_HEAD +alice$ git log -p HEAD..FETCH_HEAD ------------------------------------------------ This operation is safe even if Alice has uncommitted local changes. +The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable +from the FETCH_HEAD but exclude anything that is reachable from HEAD". +Alice already knows everything that leads to her current state (HEAD), +and reviews what Bob has in his state (FETCH_HEAD) that she has not +seen with this command. + +If Alice wants to visualize what Bob did since their histories forked +she can issue the following command: + +------------------------------------------------ +$ gitk HEAD..FETCH_HEAD +------------------------------------------------ + +This uses the same two-dot range notation we saw earlier with 'git log'. + +Alice may want to view what both of them did since they forked. +She can use three-dot form instead of the two-dot form: + +------------------------------------------------ +$ gitk HEAD...FETCH_HEAD +------------------------------------------------ + +This means "show everything that is reachable from either one, but +exclude anything that is reachable from both of them". + +Please note that these range notation can be used with both gitk +and "git log". After inspecting what Bob did, if there is nothing urgent, Alice may decide to continue working without pulling from Bob. If Bob's history @@ -341,17 +376,17 @@ it easier: alice$ git remote add bob /home/bob/myrepo ------------------------------------------------ -With this, Alice can perform the first part of the "pull" operation alone using the -'git-fetch' command without merging them with her own branch, -using: +With this, Alice can perform the first part of the "pull" operation +alone using the 'git fetch' command without merging them with her own +branch, using: ------------------------------------- alice$ git fetch bob ------------------------------------- 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 +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: ------------------------------------- @@ -368,8 +403,8 @@ could merge the changes into her master branch: alice$ git merge bob/master ------------------------------------- -This `merge` can also be done by 'pulling from her own remote -tracking branch', like this: +This `merge` can also be done by 'pulling from her own remote-tracking +branch', like this: ------------------------------------- alice$ git pull . remotes/bob/master @@ -394,7 +429,7 @@ bob$ git config --get remote.origin.url /home/alice/project ------------------------------------- -(The complete configuration created by 'git-clone' is visible using +(The complete configuration created by 'git clone' is visible using `git config -l`, and the linkgit:git-config[1] man page explains the meaning of each option.) @@ -424,7 +459,7 @@ Exploring history ----------------- Git history is represented as a series of interrelated commits. We -have already seen that the 'git-log' command can list those commits. +have already seen that the 'git log' command can list those commits. Note that first line of each git log entry also gives a name for the commit: @@ -437,7 +472,7 @@ Date: Tue May 16 17:18:22 2006 -0700 merge-base: Clarify the comments on post processing. ------------------------------------- -We can give this name to 'git-show' to see the details about this +We can give this name to 'git show' to see the details about this commit. ------------------------------------- @@ -495,13 +530,13 @@ $ 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 +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 'git-revert' +If you need to undo changes that you have pushed, use 'git revert' instead. -The 'git-grep' command can search for strings in any version of your +The 'git grep' command can search for strings in any version of your project, so ------------------------------------- @@ -510,7 +545,7 @@ $ git grep "hello" v2.5 searches for all occurrences of "hello" in v2.5. -If you leave out the commit name, 'git-grep' will search any of the +If you leave out the commit name, 'git grep' will search any of the files it manages in your current directory. So ------------------------------------- @@ -520,7 +555,7 @@ $ git grep "hello" is a quick way to search just the files that are tracked by git. Many git commands also take sets of commits, which can be specified -in a number of ways. Here are some examples with 'git-log': +in a number of ways. Here are some examples with 'git log': ------------------------------------- $ git log v2.5..v2.6 # commits between v2.5 and v2.6 @@ -530,31 +565,31 @@ $ git log v2.5.. Makefile # commits since v2.5 which modify # Makefile ------------------------------------- -You can also give 'git-log' a "range" of commits where the first is not +You can also give 'git log' a "range" of commits where the first is not necessarily an ancestor of the second; for example, if the tips of -the branches "stable-release" and "master" diverged from a common +the branches "stable" and "master" diverged from a common commit some time ago, then ------------------------------------- -$ git log stable..experimental +$ git log stable..master ------------------------------------- -will list commits made in the experimental branch but not in the +will list commits made in the master branch but not in the stable branch, while ------------------------------------- -$ git log experimental..stable +$ git log master..stable ------------------------------------- will show the list of commits made on the stable branch but not -the experimental branch. +the master branch. -The 'git-log' command has a weakness: it must present commits in a +The 'git log' command has a weakness: it must present commits in a list. When the history has lines of development that diverged and -then merged back together, the order in which 'git-log' presents +then merged back together, the order in which 'git log' presents those commits is meaningless. -Most projects with multiple contributors (such as the linux kernel, +Most projects with multiple contributors (such as the Linux kernel, or git itself) have frequent merges, and 'gitk' does a better job of visualizing their history. For example, @@ -575,7 +610,7 @@ of the file: $ git diff v2.5:Makefile HEAD:Makefile.in ------------------------------------- -You can also use 'git-show' to see any such file: +You can also use 'git show' to see any such file: ------------------------------------- $ git show v2.5:Makefile @@ -606,7 +641,7 @@ digressions that may be interesting at this point are: * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert series of git commits into emailed patches, and vice versa, - useful for projects such as the linux kernel which rely heavily + useful for projects such as the Linux kernel which rely heavily on emailed patches. * linkgit:git-bisect[1]: When there is a regression in your @@ -616,6 +651,9 @@ digressions that may be interesting at this point are: smart enough to perform a close-to-optimal search even in the case of complex non-linear history with lots of merged branches. + * linkgit:gitworkflows[7]: Gives an overview of recommended + workflows. + * link:everyday.html[Everyday GIT with 20 Commands Or So] * linkgit:gitcvs-migration[7]: Git for CVS users. @@ -626,6 +664,8 @@ linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], +linkgit:git-help[1], +linkgit:gitworkflows[7], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] |