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 a2fd5d2..5433d62 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1024,305 +1024,6 @@
moved forward to point at the head of the merged-in branch, without
any new commits being created.
-Ensuring good performance
--------------------------
-
-On large repositories, git depends on compression to keep the history
-information from taking up to much space on disk or in memory.
-
-This compression is not performed automatically. Therefore you
-should occasionally run
-
--------------------------------------------------
-$ git gc
--------------------------------------------------
-
-to recompress the archive and to prune any commits which are no
-longer referred to anywhere. This can be very time-consuming, and
-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
-into your own work.
-
-We have already seen <<Updating-a-repository-with-git-fetch,how to
-keep remote tracking branches up to date>> with gitlink:git-fetch[1],
-and how to merge two branches. So you can merge in changes from the
-original repository's master branch with:
-
--------------------------------------------------
-$ git fetch
-$ git merge origin/master
--------------------------------------------------
-
-However, the gitlink:git-pull[1] command provides a way to do this in
-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
-
--------------------------------------------------
-$ git pull
--------------------------------------------------
-
-See the descriptions of the branch.<name>.remote and
-branch.<name>.merge options in gitlink:git-repo-config[1] to learn
-how to control these defaults depending on the current branch.
-
-In addition to saving you keystrokes, "git pull" also helps you by
-producing a default commit message documenting the branch and
-repository that you pulled from.
-
-(But note that no such commit will be created in the case of a
-<<fast-forwards,fast forward>>; instead, your branch will just be
-updated to point to the latest commit from the upstream branch).
-
-The git-pull command can also be given "." as the "remote" repository, in
-which case it just merges in a branch from the current repository; so
-the commands
-
--------------------------------------------------
-$ git pull . branch
-$ 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:
-
-First, use gitlink:git-format-patches[1]; for example:
-
--------------------------------------------------
-$ git format-patches origin
--------------------------------------------------
-
-will produce a numbered series of files in the current directory, one
-for each patch in the current branch but not in origin/HEAD.
-
-You can then import these into your mail client and send them by
-hand. However, if you have a lot to send at once, you may prefer to
-use the gitlink:git-send-email[1] script to automate the process.
-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.
-Just save all of the patch-containing messages, in order, into a
-single mailbox file, say "patches.mbox", then run
-
--------------------------------------------------
-$ git am patches.mbox
--------------------------------------------------
-
-Git will apply each patch in order; if any conflicts are found, it
-will stop, and you can fix the conflicts as described in
-"<<resolving-a-merge,Resolving a merge>>". Once the index is updated
-with the results of the conflict resolution, instead of creating a
-new commit, just run
-
--------------------------------------------------
-$ git am --resolved
--------------------------------------------------
-
-and git will create the commit for you and continue applying the
-remaining patches from the mailbox.
-
-The final result will be a series of commits, one for each patch in
-the original mailbox, with authorship and commit log message each
-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
-you did in the section "<<getting-updates-with-git-pull, Getting
-updates with git pull>>".
-
-If you and maintainer both have accounts on the same machine, then
-then you can just pull changes from each other's repositories
-directly; note that all of the command (gitlink:git-clone[1],
-git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
-will also accept a local file patch; so, for example, you can
-use
-
--------------------------------------------------
-$ git clone /path/to/repository
-$ git pull /path/to/other/repository
--------------------------------------------------
-
-If this sort of setup is inconvenient or impossible, another (more
-common) option is to set up a public repository on a public server.
-This also allows you to cleanly separate private work in progress
-from publicly visible work.
-
-You will continue to do your day-to-day work in your personal
-repository, but periodically "push" changes from your personal
-repository into your public repository, allowing other developers to
-pull from that repository. So the flow of changes, in a situation
-where there is one other developer with a public repository, looks
-like this:
-
- you push
- your personal repo ------------------> your public repo
- ^ |
- | |
- | you pull | they pull
- | |
- | |
- | they push V
- their public repo <------------------- their repo
-
-Now, assume your personal repository is in the directory ~/proj. We
-first create a new clone of the repository:
-
--------------------------------------------------
-$ git clone --bare proj-clone.git
--------------------------------------------------
-
-The resulting directory proj-clone.git will contains a "bare" git
-repository--it is just the contents of the ".git" directory, without
-a checked-out copy of a working directory.
-
-Next, copy proj-clone.git to the server where you plan to host the
-public repository. You can use scp, rsync, or whatever is most
-convenient.
-
-If somebody else maintains the public server, they may already have
-set up a git service for you, and you may skip to the section
-"<<pushing-changes-to-a-public-repository,Pushing changes to a public
-repository>>", below.
-
-Otherwise, the following sections explain how to export your newly
-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.
-
-All you need to do is place the newly created bare git repository in
-a directory that is exported by the web server, and make some
-adjustments to give web clients some extra information they need:
-
--------------------------------------------------
-$ mv proj.git /home/you/public_html/proj.git
-$ cd proj.git
-$ git update-server-info
-$ chmod a+x hooks/post-update
--------------------------------------------------
-
-(For an explanation of the last two lines, see
-gitlink:git-update-server-info[1], and the documentation
-link:hooks.txt[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:
-
--------------------------------------------------
-$ git clone http://yourserver.com/~you/proj.git
--------------------------------------------------
-
-(See also
-link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
-for a slightly more sophisticated setup using WebDAV which also
-allows pushing over http.)
-
-[[exporting-via-git]]
-Exporting a git repository via the git protocol
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is the preferred method.
-
-For now, we refer you to the gitlink:git-daemon[1] man page for
-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
-maintainers to fetch your latest changes, but they do not allow write
-access, which you will need to update the public repository with the
-latest changes created in your private repository.
-
-The simplest way to do this is using gitlink:git-push[1] and ssh; to
-update the remote branch named "master" with the latest state of your
-branch named "master", run
-
--------------------------------------------------
-$ git push ssh://yourserver.com/~you/proj.git master:master
--------------------------------------------------
-
-or just
-
--------------------------------------------------
-$ git push ssh://yourserver.com/~you/proj.git master
--------------------------------------------------
-
-As with git-fetch, git-push will complain if this does not result in
-a <<fast-forwards,fast forward>>. Normally this is a sign of
-something wrong. However, if you are sure you know what you're
-doing, you may force git-push to perform the update anyway by
-proceeding the branch name by a plus sign:
-
--------------------------------------------------
-$ git push ssh://yourserver.com/~you/proj.git +master
--------------------------------------------------
-
-As with git-fetch, you may also set up configuration options to
-save typing; so, for example, after
-
--------------------------------------------------
-$ cat >.git/config <<EOF
-[remote "public-repo"]
- url = ssh://yourserver.com/~you/proj.git
-EOF
--------------------------------------------------
-
-you should be able to perform the above push with just
-
--------------------------------------------------
-$ git push public-repo master
--------------------------------------------------
-
-See the explanations of the remote.<name>.url, branch.<name>.remote,
-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
-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
---------------
@@ -1426,6 +1127,316 @@
which will display the given version of the file.
+Ensuring good performance
+-------------------------
+
+On large repositories, git depends on compression to keep the history
+information from taking up to much space on disk or in memory.
+
+This compression is not performed automatically. Therefore you
+should occasionally run
+
+-------------------------------------------------
+$ git gc
+-------------------------------------------------
+
+to recompress the archive and to prune any commits which are no
+longer referred to anywhere. This can be very time-consuming, and
+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
+into your own work.
+
+We have already seen <<Updating-a-repository-with-git-fetch,how to
+keep remote tracking branches up to date>> with gitlink:git-fetch[1],
+and how to merge two branches. So you can merge in changes from the
+original repository's master branch with:
+
+-------------------------------------------------
+$ git fetch
+$ git merge origin/master
+-------------------------------------------------
+
+However, the gitlink:git-pull[1] command provides a way to do this in
+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
+
+-------------------------------------------------
+$ git pull
+-------------------------------------------------
+
+See the descriptions of the branch.<name>.remote and
+branch.<name>.merge options in gitlink:git-repo-config[1] to learn
+how to control these defaults depending on the current branch.
+
+In addition to saving you keystrokes, "git pull" also helps you by
+producing a default commit message documenting the branch and
+repository that you pulled from.
+
+(But note that no such commit will be created in the case of a
+<<fast-forwards,fast forward>>; instead, your branch will just be
+updated to point to the latest commit from the upstream branch).
+
+The git-pull command can also be given "." as the "remote" repository, in
+which case it just merges in a branch from the current repository; so
+the commands
+
+-------------------------------------------------
+$ git pull . branch
+$ 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:
+
+First, use gitlink:git-format-patches[1]; for example:
+
+-------------------------------------------------
+$ git format-patches origin
+-------------------------------------------------
+
+will produce a numbered series of files in the current directory, one
+for each patch in the current branch but not in origin/HEAD.
+
+You can then import these into your mail client and send them by
+hand. However, if you have a lot to send at once, you may prefer to
+use the gitlink:git-send-email[1] script to automate the process.
+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.
+Just save all of the patch-containing messages, in order, into a
+single mailbox file, say "patches.mbox", then run
+
+-------------------------------------------------
+$ git am patches.mbox
+-------------------------------------------------
+
+Git will apply each patch in order; if any conflicts are found, it
+will stop, and you can fix the conflicts as described in
+"<<resolving-a-merge,Resolving a merge>>". Once the index is updated
+with the results of the conflict resolution, instead of creating a
+new commit, just run
+
+-------------------------------------------------
+$ git am --resolved
+-------------------------------------------------
+
+and git will create the commit for you and continue applying the
+remaining patches from the mailbox.
+
+The final result will be a series of commits, one for each patch in
+the original mailbox, with authorship and commit log message each
+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
+you did in the section "<<getting-updates-with-git-pull, Getting
+updates with git pull>>".
+
+If you and maintainer both have accounts on the same machine, then
+then you can just pull changes from each other's repositories
+directly; note that all of the command (gitlink:git-clone[1],
+git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
+will also accept a local file patch; so, for example, you can
+use
+
+-------------------------------------------------
+$ git clone /path/to/repository
+$ git pull /path/to/other/repository
+-------------------------------------------------
+
+If this sort of setup is inconvenient or impossible, another (more
+common) option is to set up a public repository on a public server.
+This also allows you to cleanly separate private work in progress
+from publicly visible work.
+
+You will continue to do your day-to-day work in your personal
+repository, but periodically "push" changes from your personal
+repository into your public repository, allowing other developers to
+pull from that repository. So the flow of changes, in a situation
+where there is one other developer with a public repository, looks
+like this:
+
+ you push
+ your personal repo ------------------> your public repo
+ ^ |
+ | |
+ | you pull | they pull
+ | |
+ | |
+ | they push V
+ their public repo <------------------- their repo
+
+Now, assume your personal repository is in the directory ~/proj. We
+first create a new clone of the repository:
+
+-------------------------------------------------
+$ git clone --bare proj-clone.git
+-------------------------------------------------
+
+The resulting directory proj-clone.git will contains a "bare" git
+repository--it is just the contents of the ".git" directory, without
+a checked-out copy of a working directory.
+
+Next, copy proj-clone.git to the server where you plan to host the
+public repository. You can use scp, rsync, or whatever is most
+convenient.
+
+If somebody else maintains the public server, they may already have
+set up a git service for you, and you may skip to the section
+"<<pushing-changes-to-a-public-repository,Pushing changes to a public
+repository>>", below.
+
+Otherwise, the following sections explain how to export your newly
+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.
+
+All you need to do is place the newly created bare git repository in
+a directory that is exported by the web server, and make some
+adjustments to give web clients some extra information they need:
+
+-------------------------------------------------
+$ mv proj.git /home/you/public_html/proj.git
+$ cd proj.git
+$ git update-server-info
+$ chmod a+x hooks/post-update
+-------------------------------------------------
+
+(For an explanation of the last two lines, see
+gitlink:git-update-server-info[1], and the documentation
+link:hooks.txt[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:
+
+-------------------------------------------------
+$ git clone http://yourserver.com/~you/proj.git
+-------------------------------------------------
+
+(See also
+link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
+for a slightly more sophisticated setup using WebDAV which also
+allows pushing over http.)
+
+[[exporting-via-git]]
+Exporting a git repository via the git protocol
+-----------------------------------------------
+
+This is the preferred method.
+
+For now, we refer you to the gitlink:git-daemon[1] man page for
+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
+maintainers to fetch your latest changes, but they do not allow write
+access, which you will need to update the public repository with the
+latest changes created in your private repository.
+
+The simplest way to do this is using gitlink:git-push[1] and ssh; to
+update the remote branch named "master" with the latest state of your
+branch named "master", run
+
+-------------------------------------------------
+$ git push ssh://yourserver.com/~you/proj.git master:master
+-------------------------------------------------
+
+or just
+
+-------------------------------------------------
+$ git push ssh://yourserver.com/~you/proj.git master
+-------------------------------------------------
+
+As with git-fetch, git-push will complain if this does not result in
+a <<fast-forwards,fast forward>>. Normally this is a sign of
+something wrong. However, if you are sure you know what you're
+doing, you may force git-push to perform the update anyway by
+proceeding the branch name by a plus sign:
+
+-------------------------------------------------
+$ git push ssh://yourserver.com/~you/proj.git +master
+-------------------------------------------------
+
+As with git-fetch, you may also set up configuration options to
+save typing; so, for example, after
+
+-------------------------------------------------
+$ cat >.git/config <<EOF
+[remote "public-repo"]
+ url = ssh://yourserver.com/~you/proj.git
+EOF
+-------------------------------------------------
+
+you should be able to perform the above push with just
+
+-------------------------------------------------
+$ git push public-repo master
+-------------------------------------------------
+
+See the explanations of the remote.<name>.url, branch.<name>.remote,
+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
+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.
+
+Allow web browsing of a repository
+----------------------------------
+
+TODO: Brief setup-instructions for gitweb
+
+Examples
+--------
+
+TODO: topic branches, typical roles as in everyday.txt, ?
+
+
Working with other version control systems
==========================================
@@ -1623,10 +1634,8 @@
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 @@
"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.
