user-manual: reorganize public git repo discussion
Helping a couple people set up public repos recently, I wanted to point them at this piece of the user manual, but found it wasn't as helpful as it could be: - It starts with a big explanation of why you'd want a public repository, not necessary in their case since they already knew why they wanted that. So, separate that out. - It skimps on some of the git-daemon details, and puts the http export information first. Fix that. Also group all the public repo subsections into a single section, and do some miscellaneous related editing. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
May 15, 2007 at 00:00 UTC
eda694491933ac5f209892f3e284b648bb0185a0
1 file changed
+50
-40
Documentation/user-manual.txt
+50
-40
@@ -1674,31 +1674,30 @@ The final result will be a series of commits, one for each patch in
1674
the original mailbox, with authorship and commit log message each
1675
taken from the message containing each patch.
1676
1677
-[[setting-up-a-public-repository]]
1678
-Setting up a public repository
1679
-------------------------------
1677
+[[public-repositories]]
1678
+Public git repositories
1679
+-----------------------
1680
1681
-Another way to submit changes to a project is to simply tell the
1682
-maintainer of that project to pull from your repository, exactly as
1683
-you did in the section "<<getting-updates-with-git-pull, Getting
1684
-updates with git pull>>".
1681
+Another way to submit changes to a project is to tell the maintainer of
1682
+that project to pull the changes from your repository using git-pull[1].
1683
+In the section "<<getting-updates-with-git-pull, Getting updates with
1684
+git pull>>" we described this as a way to get updates from the "main"
1685
+repository, but it works just as well in the other direction.
1686
1686
-If you and maintainer both have accounts on the same machine, then
1687
-then you can just pull changes from each other's repositories
1688
-directly; note that all of the commands (gitlink:git-clone[1],
1689
-git-fetch[1], git-pull[1], etc.) that accept a URL as an argument
1690
-will also accept a local directory name; so, for example, you can
1691
-use
1687
+If you and the maintainer both have accounts on the same machine, then
1688
+you can just pull changes from each other's repositories directly;
1689
+commands that accepts repository URLs as arguments will also accept a
1690
+local directory name:
1691
1692
-------------------------------------------------
1693
$ git clone /path/to/repository
1694
$ git pull /path/to/other/repository
1695
-------------------------------------------------
1696
1698
-If this sort of setup is inconvenient or impossible, another (more
1699
-common) option is to set up a public repository on a public server.
1700
-This also allows you to cleanly separate private work in progress
1701
-from publicly visible work.
1697
+However, the more common way to do this is to maintain a separate public
1698
+repository (usually on a different host) for others to pull changes
1699
+from. This is usually more convenient, and allows you to cleanly
1700
+separate private work in progress from publicly visible work.
1701
1702
You will continue to do your day-to-day work in your personal
1703
repository, but periodically "push" changes from your personal
@@ -1717,32 +1716,52 @@ like this:
1716
| they push V
1717
their public repo <------------------- their repo
1718
1720
-Now, assume your personal repository is in the directory ~/proj. We
1721
-first create a new clone of the repository:
1719
+[[setting-up-a-public-repository]]
1720
+Setting up a public repository
1721
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1722
+
1723
+Assume your personal repository is in the directory ~/proj. We
1724
+first create a new clone of the repository and tell git-daemon that it
1725
+is meant to be public:
1726
1727
-------------------------------------------------
1728
$ git clone --bare ~/proj proj.git
1729
+$ touch proj.git/git-daemon-export-ok
1730
-------------------------------------------------
1731
1732
The resulting directory proj.git contains a "bare" git repository--it is
1728
-just the contents of the ".git" directory, without a checked-out copy of
1729
-a working directory.
1733
+just the contents of the ".git" directory, without any files checked out
1734
+around it.
1735
1736
Next, copy proj.git to the server where you plan to host the
1737
public repository. You can use scp, rsync, or whatever is most
1738
convenient.
1739
1735
-If somebody else maintains the public server, they may already have
1736
-set up a git service for you, and you may skip to the section
1740
+[[exporting-via-git]]
1741
+Exporting a git repository via the git protocol
1742
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1743
+
1744
+This is the preferred method.
1745
+
1746
+If someone else administers the server, they should tell you what
1747
+directory to put the repository in, and what git:// url it will appear
1748
+at. You can then skip to the section
1749
"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1750
repository>>", below.
1751
1740
-Otherwise, the following sections explain how to export your newly
1741
-created public repository:
1752
+Otherwise, all you need to do is start gitlink:git-daemon[1]; it will
1753
+listen on port 9418. By default, it will allow access to any directory
1754
+that looks like a git directory and contains the magic file
1755
+git-daemon-export-ok. Passing some directory paths as git-daemon
1756
+arguments will further restrict the exports to those paths.
1757
+
1758
+You can also run git-daemon as an inetd service; see the
1759
+gitlink:git-daemon[1] man page for details. (See especially the
1760
+examples section.)
1761
1762
[[exporting-via-http]]
1763
Exporting a git repository via http
1745
------------------------------------
1764
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1765
1766
The git protocol gives better performance and reliability, but on a
1767
host with a web server set up, http exports may be simpler to set up.
@@ -1774,20 +1793,11 @@ link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1793
for a slightly more sophisticated setup using WebDAV which also
1794
allows pushing over http.)
1795
1777
-[[exporting-via-git]]
1778
-Exporting a git repository via the git protocol
1779
------------------------------------------------
1780
-
1781
-This is the preferred method.
1782
-
1783
-For now, we refer you to the gitlink:git-daemon[1] man page for
1784
-instructions. (See especially the examples section.)
1785
-
1796
[[pushing-changes-to-a-public-repository]]
1797
Pushing changes to a public repository
1788
---------------------------------------
1798
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1799
1790
-Note that the two techniques outline above (exporting via
1800
+Note that the two techniques outlined above (exporting via
1801
<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1802
maintainers to fetch your latest changes, but they do not allow write
1803
access, which you will need to update the public repository with the
@@ -1839,7 +1849,7 @@ details.
1849
1850
[[setting-up-a-shared-repository]]
1851
Setting up a shared repository
1842
-------------------------------
1852
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1853
1854
Another way to collaborate is by using a model similar to that
1855
commonly used in CVS, where several developers with special rights
@@ -1848,8 +1858,8 @@ link:cvs-migration.txt[git for CVS users] for instructions on how to
1858
set this up.
1859
1860
[[setting-up-gitweb]]
1851
-Allow web browsing of a repository
1852
-----------------------------------
1861
+Allowing web browsing of a repository
1862
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1863
1864
The gitweb cgi script provides users an easy way to browse your
1865
project's files and history without having to install git; see the file