Documentation: reorder development section, todo's

Update todo's.  Split out "sharing development" section into a separate
chapter, reorder.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a2fd5d27561a0893ab2ab95626729c1e34504256..5433d624d72c9e46588939d662eacbad6ef473b5 100644 (file)
--- 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.