diff options
| -rw-r--r-- | Documentation/user-manual.txt | 243 |
1 files changed, 123 insertions, 120 deletions
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index a2fd5d2756..5433d624d7 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1024,6 +1024,109 @@ already contained in the other--then git just performs a moved forward to point at the head of the merged-in branch, without any new commits being created. +Fixing mistakes +--------------- + +If you've messed up the working tree, but haven't yet committed your +mistake, you can return the entire working tree to the last committed +state with + +------------------------------------------------- +$ git reset --hard HEAD +------------------------------------------------- + +If you make a commit that you later wish you hadn't, there are two +fundamentally different ways to fix the problem: + + 1. You can create a new commit that undoes whatever was done + by the previous commit. This is the correct thing if your + mistake has already been made public. + + 2. You can go back and modify the old commit. You should + never do this if you have already made the history public; + git does not normally expect the "history" of a project to + change, and cannot correctly perform repeated merges from + a branch that has had its history changed. + +Fixing a mistake with a new commit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creating a new commit that reverts an earlier change is very easy; +just pass the gitlink:git-revert[1] command a reference to the bad +commit; for example, to revert the most recent commit: + +------------------------------------------------- +$ git revert HEAD +------------------------------------------------- + +This will create a new commit which undoes the change in HEAD. You +will be given a chance to edit the commit message for the new commit. + +You can also revert an earlier change, for example, the next-to-last: + +------------------------------------------------- +$ git revert HEAD^ +------------------------------------------------- + +In this case git will attempt to undo the old change while leaving +intact any changes made since then. If more recent changes overlap +with the changes to be reverted, then you will be asked to fix +conflicts manually, just as in the case of <<resolving-a-merge, +resolving a merge>>. + +Fixing a mistake by editing history +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the problematic commit is the most recent commit, and you have not +yet made that commit public, then you may just +<<undoing-a-merge,destroy it using git-reset>>. + +Alternatively, you +can edit the working directory and update the index to fix your +mistake, just as if you were going to <<how-to-make-a-commit,create a +new commit>>, then run + +------------------------------------------------- +$ git commit --amend +------------------------------------------------- + +which will replace the old commit by a new commit incorporating your +changes, giving you a chance to edit the old commit message first. + +Again, you should never do this to a commit that may already have +been merged into another branch; use gitlink:git-revert[1] instead in +that case. + +It is also possible to edit commits further back in the history, but +this is an advanced topic to be left for +<<cleaning-up-history,another chapter>>. + +Checking out an old version of a file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the process of undoing a previous bad change, you may find it +useful to check out an older version of a particular file using +gitlink:git-checkout[1]. We've used git checkout before to switch +branches, but it has quite different behavior if it is given a path +name: the command + +------------------------------------------------- +$ git checkout HEAD^ path/to/file +------------------------------------------------- + +replaces path/to/file by the contents it had in the commit HEAD^, and +also updates the index to match. It does not change branches. + +If you just want to look at an old version of the file, without +modifying the working directory, you can do that with +gitlink:git-show[1]: + +------------------------------------------------- +$ git show HEAD^ path/to/file +------------------------------------------------- + +which will display the given version of the file. + Ensuring good performance ------------------------- @@ -1043,11 +1146,11 @@ you should not modify the repository while it is working, so you should run it while you are not working. Sharing development with others -------------------------------- +=============================== [[getting-updates-with-git-pull]] Getting updates with git pull -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- After you clone a repository and make a few changes of your own, you may wish to check the original repository for updates and merge them @@ -1102,7 +1205,7 @@ $ git merge branch are roughly equivalent. The former is actually very commonly used. Submitting patches to a project -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------- If you just have a few changes, the simplest way to submit them may just be to send them as patches in email: @@ -1123,7 +1226,7 @@ Consult the mailing list for your project first to determine how they prefer such patches be handled. Importing patches to a project -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ Git also provides a tool called gitlink:git-am[1] (am stands for "apply mailbox"), for importing such an emailed series of patches. @@ -1153,7 +1256,7 @@ taken from the message containing each patch. [[setting-up-a-public-repository]] Setting up a public repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ Another way to submit changes to a project is to simply tell the maintainer of that project to pull from your repository, exactly as @@ -1219,7 +1322,7 @@ created public repository: [[exporting-via-http]] Exporting a git repository via http -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------- The git protocol gives better performance and reliability, but on a host with a web server set up, http exports may be simpler to set up. @@ -1253,7 +1356,7 @@ allows pushing over http.) [[exporting-via-git]] Exporting a git repository via the git protocol -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------------- This is the preferred method. @@ -1262,7 +1365,7 @@ instructions. (See especially the examples section.) [[pushing-changes-to-a-public-repository]] Pushing changes to a public repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------- Note that the two techniques outline above (exporting via <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other @@ -1315,7 +1418,7 @@ and remote.<name>.push options in gitlink:git-repo-config[1] for details. Setting up a shared repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ Another way to collaborate is by using a model similar to that commonly used in CVS, where several developers with special rights @@ -1323,108 +1426,16 @@ all push to and pull from a single shared repository. See link:cvs-migration.txt[git for CVS users] for instructions on how to set this up. -Fixing mistakes ---------------- - -If you've messed up the working tree, but haven't yet committed your -mistake, you can return the entire working tree to the last committed -state with - -------------------------------------------------- -$ git reset --hard HEAD -------------------------------------------------- - -If you make a commit that you later wish you hadn't, there are two -fundamentally different ways to fix the problem: - - 1. You can create a new commit that undoes whatever was done - by the previous commit. This is the correct thing if your - mistake has already been made public. - - 2. You can go back and modify the old commit. You should - never do this if you have already made the history public; - git does not normally expect the "history" of a project to - change, and cannot correctly perform repeated merges from - a branch that has had its history changed. - -Fixing a mistake with a new commit -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Creating a new commit that reverts an earlier change is very easy; -just pass the gitlink:git-revert[1] command a reference to the bad -commit; for example, to revert the most recent commit: - -------------------------------------------------- -$ git revert HEAD -------------------------------------------------- - -This will create a new commit which undoes the change in HEAD. You -will be given a chance to edit the commit message for the new commit. - -You can also revert an earlier change, for example, the next-to-last: - -------------------------------------------------- -$ git revert HEAD^ -------------------------------------------------- - -In this case git will attempt to undo the old change while leaving -intact any changes made since then. If more recent changes overlap -with the changes to be reverted, then you will be asked to fix -conflicts manually, just as in the case of <<resolving-a-merge, -resolving a merge>>. - -Fixing a mistake by editing history -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Allow web browsing of a repository +---------------------------------- -If the problematic commit is the most recent commit, and you have not -yet made that commit public, then you may just -<<undoing-a-merge,destroy it using git-reset>>. +TODO: Brief setup-instructions for gitweb -Alternatively, you -can edit the working directory and update the index to fix your -mistake, just as if you were going to <<how-to-make-a-commit,create a -new commit>>, then run +Examples +-------- -------------------------------------------------- -$ git commit --amend -------------------------------------------------- +TODO: topic branches, typical roles as in everyday.txt, ? -which will replace the old commit by a new commit incorporating your -changes, giving you a chance to edit the old commit message first. - -Again, you should never do this to a commit that may already have -been merged into another branch; use gitlink:git-revert[1] instead in -that case. - -It is also possible to edit commits further back in the history, but -this is an advanced topic to be left for -<<cleaning-up-history,another chapter>>. - -Checking out an old version of a file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the process of undoing a previous bad change, you may find it -useful to check out an older version of a particular file using -gitlink:git-checkout[1]. We've used git checkout before to switch -branches, but it has quite different behavior if it is given a path -name: the command - -------------------------------------------------- -$ git checkout HEAD^ path/to/file -------------------------------------------------- - -replaces path/to/file by the contents it had in the commit HEAD^, and -also updates the index to match. It does not change branches. - -If you just want to look at an old version of the file, without -modifying the working directory, you can do that with -gitlink:git-show[1]: - -------------------------------------------------- -$ git show HEAD^ path/to/file -------------------------------------------------- - -which will display the given version of the file. Working with other version control systems ========================================== @@ -1623,10 +1634,8 @@ Scan email archives for other stuff left out Scan man pages to see if any assume more background than this manual provides. -Mention of gitweb. - -Update git fetch discussion to use "git remote" setup. That will -make things simpler. Maybe wait till git remote is done. +Update git fetch discussion to use "git remote", move most of branch +discussion till later. Can also simplify beginning by suggesting disconnected head instead of temporary branch creation. @@ -1636,18 +1645,12 @@ section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The "git ls-files --unmerged --stage" thing is sorta useful too, actually. And note gitk --merge. Also what's easiest way to see common merge base? -Add more good examples. Entire sections of just cookbook examples might be a -good idea; maybe make an "advanced examples" section a standard end-of-chapter -section? +Add more good examples. Entire sections of just cookbook examples might +be a good idea; maybe make an "advanced examples" section a standard +end-of-chapter section? Include cross-references to the glossary, where appropriate. -Update for detached-head. - -Update for git-remote. Even if the command isn't there yet, I think we should -probably just document the repository configuration necessary to set it up, as -the default way to keep a repository up-to-date. - To document: reflogs, git reflog expire shallow clones?? See draft 1.5.0 release notes for some documentation. |