diff options
Diffstat (limited to 'Documentation/user-manual.txt')
| -rw-r--r-- | Documentation/user-manual.txt | 130 |
1 files changed, 82 insertions, 48 deletions
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 2e8c050..06ab79f 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1,10 +1,10 @@ -Git User's Manual (for version 1.5.1 or newer) +Git User's Manual (for version 1.5.3 or newer) ______________________________________________ Git is a fast distributed revision control system. -This manual is designed to be readable by someone with basic unix +This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of git. <<repositories-and-branches>> and <<exploring-git-history>> explain how @@ -208,7 +208,7 @@ commits will help understand how the git organizes history. In the following, we say that commit X is "reachable" from commit Y if commit X is an ancestor of commit Y. Equivalently, you could say -that Y is a descendent of X, or that there is a chain of parents +that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X. [[history-diagrams]] @@ -440,7 +440,7 @@ Exploring git history Git is best thought of as a tool for storing the history of a collection of files. It does this by storing compressed snapshots of -the contents of a file heirarchy, together with "commits" which show +the contents of a file hierarchy, together with "commits" which show the relationships between these snapshots. Git provides extremely flexible and fast tools for exploring the @@ -1048,7 +1048,7 @@ $ git show ------------------------------------------------- As a special shortcut, - + ------------------------------------------------- $ git commit -a ------------------------------------------------- @@ -1061,7 +1061,7 @@ about to commit: ------------------------------------------------- $ git diff --cached # difference between HEAD and the index; what - # would be commited if you ran "commit" now. + # would be committed if you ran "commit" now. $ git diff # difference between the index file and your # working directory; changes that would not # be included if you ran "commit" now. @@ -1070,6 +1070,11 @@ $ git diff HEAD # difference between HEAD and working tree; what $ git status # a brief per-file summary of the above. ------------------------------------------------- +You can also use gitlink:git-gui[1] to create commits, view changes in +the index and the working tree files, and individually select diff hunks +for inclusion in the index (by right-clicking on the diff hunk and +choosing "Stage Hunk For Commit"). + [[creating-good-commit-messages]] Creating good commit messages ----------------------------- @@ -1221,7 +1226,7 @@ index 802992c,2b60207..0000000 ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt ------------------------------------------------- -Recall that the commit which will be commited after we resolve this +Recall that the commit which will be committed after we resolve this conflict will have two parents instead of the usual one: one parent will be HEAD, the tip of the current branch; the other will be the tip of the other branch, which is stored temporarily in MERGE_HEAD. @@ -1315,7 +1320,7 @@ away, you can always return to the pre-merge state with $ git reset --hard HEAD ------------------------------------------------- -Or, if you've already commited the merge that you want to throw away, +Or, if you've already committed the merge that you want to throw away, ------------------------------------------------- $ git reset --hard ORIG_HEAD @@ -1448,6 +1453,38 @@ $ git show HEAD^:path/to/file which will display the given version of the file. +[[interrupted-work]] +Temporarily setting aside work in progress +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While you are in the middle of working on something complicated, you +find an unrelated but obvious and trivial bug. You would like to fix it +before continuing. You can use gitlink:git-stash[1] to save the current +state of your work, and after fixing the bug (or, optionally after doing +so on a different branch and then coming back), unstash the +work-in-progress changes. + +------------------------------------------------ +$ git stash "work in progress for foo feature" +------------------------------------------------ + +This command will save your changes away to the `stash`, and +reset your working tree and the index to match the tip of your +current branch. Then you can make your fix as usual. + +------------------------------------------------ +... edit and test ... +$ git commit -a -m "blorpl: typofix" +------------------------------------------------ + +After that, you can go back to what you were working on with +`git stash apply`: + +------------------------------------------------ +$ git stash apply +------------------------------------------------ + + [[ensuring-good-performance]] Ensuring good performance ------------------------- @@ -1519,7 +1556,7 @@ history. Fortunately, git also keeps a log, called a "reflog", of all the previous values of each branch. So in this case you can still find the -old history using, for example, +old history using, for example, ------------------------------------------------- $ git log master@{1} @@ -1595,7 +1632,7 @@ If you decide you want the history back, you can always create a new reference pointing to it, for example, a new branch: ------------------------------------------------ -$ git branch recovered-branch 7281251ddd +$ git branch recovered-branch 7281251ddd ------------------------------------------------ Other types of dangling objects (blobs and trees) are also possible, and @@ -1631,24 +1668,19 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, "origin" is normally the default repository to pull from, -and the default branch is normally the HEAD of the remote repository, -so often you can accomplish the above with just +In fact, if you have "master" checked out, then by default "git pull" +merges from the HEAD branch of the origin repository. So often you can +accomplish the above with just a simple ------------------------------------------------- $ git pull ------------------------------------------------- -See the descriptions of the branch.<name>.remote and branch.<name>.merge -options in gitlink:git-config[1] to learn how to control these defaults -depending on the current branch. Also note that the --track option to -gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to -automatically set the default remote branch to pull from at the time -that a branch is created: - -------------------------------------------------- -$ git checkout --track -b maint origin/maint -------------------------------------------------- +More generally, a branch that is created from a remote branch will pull +by default from that branch. See the descriptions of the +branch.<name>.remote and branch.<name>.merge options in +gitlink:git-config[1], and the discussion of the --track option in +gitlink:git-checkout[1], to learn how to control these defaults. In addition to saving you keystrokes, "git pull" also helps you by producing a default commit message documenting the branch and @@ -1768,7 +1800,7 @@ like this: you push your personal repo ------------------> your public repo - ^ | + ^ | | | | you pull | they pull | | @@ -1844,7 +1876,7 @@ gitlink:git-update-server-info[1], and the documentation link:hooks.html[Hooks used by git].) Advertise the url of proj.git. Anybody else should then be able to -clone or pull from that url, for example with a commandline like: +clone or pull from that url, for example with a command line like: ------------------------------------------------- $ git clone http://yourserver.com/~you/proj.git @@ -2343,7 +2375,7 @@ the result would create a new merge commit, like this: \ \ a--b--c--m <-- mywork ................................................ - + However, if you prefer to keep the history in mywork a simple series of commits without any merges, you may instead choose to use gitlink:git-rebase[1]: @@ -2445,8 +2477,10 @@ $ gitk origin..mywork & And browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using commit ---amend. +cherry-pick, and possibly modifying them as you go using commit --amend. +The gitlink:git-gui[1] command may also help as it allows you to +individually select diff hunks for inclusion in the index (by +right-clicking on the diff hunk and choosing "Stage Hunk for Commit"). Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches: @@ -2463,7 +2497,7 @@ them again with gitlink:git-am[1]. Other tools ----------- -There are numerous other tools, such as stgit, which exist for the +There are numerous other tools, such as StGIT, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual. @@ -2719,7 +2753,7 @@ must have at least one root, and while you can tie several different root objects together into one project by creating a commit object which has two or more separate roots as its ultimate parents, that's probably just going to confuse people. So aim for the notion of "one root object -per project", even if git itself does not enforce that. +per project", even if git itself does not enforce that. A <<def_tag_object,"tag" object>> symbolically identifies and can be used to sign other objects. It contains the identifier and type of @@ -2938,15 +2972,15 @@ cache, and the normal operation is to re-generate it completely from a known tree object, or update/compare it with a live tree that is being developed. If you blow the directory cache away entirely, you generally haven't lost any information as long as you have the name of the tree -that it described. +that it described. -At the same time, the index is at the same time also the -staging area for creating new trees, and creating a new tree always -involves a controlled modification of the index file. In particular, -the index file can have the representation of an intermediate tree that -has not yet been instantiated. So the index can be thought of as a -write-back cache, which can contain dirty information that has not yet -been written back to the backing store. +At the same time, the index is also the staging area for creating +new trees, and creating a new tree always involves a controlled +modification of the index file. In particular, the index file can +have the representation of an intermediate tree that has not yet been +instantiated. So the index can be thought of as a write-back cache, +which can contain dirty information that has not yet been written back +to the backing store. @@ -2958,7 +2992,7 @@ Generally, all "git" operations work on the index file. Some operations work *purely* on the index file (showing the current state of the index), but most operations move data to and from the index file. Either from the database or from the working directory. Thus there are four -main combinations: +main combinations: [[working-directory-to-index]] working directory -> index @@ -3421,7 +3455,7 @@ because you interrupted a "git fetch" with ^C or something like that, leaving _some_ of the new objects in the object database, but just dangling and useless. -Anyway, once you are sure that you're not interested in any dangling +Anyway, once you are sure that you're not interested in any dangling state, you can just prune all unreachable objects: ------------------------------------------------ @@ -3432,12 +3466,12 @@ and they'll be gone. But you should only run "git prune" on a quiescent repository - it's kind of like doing a filesystem fsck recovery: you don't want to do that while the filesystem is mounted. -(The same is true of "git-fsck" itself, btw - but since -git-fsck never actually *changes* the repository, it just reports -on what it found, git-fsck itself is never "dangerous" to run. -Running it while somebody is actually changing the repository can cause -confusing and scary messages, but it won't actually do anything bad. In -contrast, running "git prune" while somebody is actively changing the +(The same is true of "git-fsck" itself, btw - but since +git-fsck never actually *changes* the repository, it just reports +on what it found, git-fsck itself is never "dangerous" to run. +Running it while somebody is actually changing the repository can cause +confusing and scary messages, but it won't actually do anything bad. In +contrast, running "git prune" while somebody is actively changing the repository is a *BAD* idea). [[birdview-on-the-source-code]] @@ -3893,8 +3927,8 @@ This is a work in progress. The basic requirements: - It must be readable in order, from beginning to end, by - someone intelligent with a basic grasp of the unix - commandline, but without any special knowledge of git. If + someone intelligent with a basic grasp of the UNIX + command line, but without any special knowledge of git. If necessary, any other prerequisites should be specifically mentioned as they arise. - Whenever possible, section headings should clearly describe |