{"thread":{"id":"8197","subject":"Documentation (mainly user-manual) patches","startedAt":"2007-05-18T03:37:46Z","lastAt":"2007-05-19T05:19:20Z","messageCount":8,"participants":["J. Bruce Fields","Petr Baudis","Shawn O. Pearce"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"42443","messageId":"20070518033746.GB30144@fieldses.org","threadId":"8197","inReplyTo":null,"subject":"Documentation (mainly user-manual) patches","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-05-18T03:37:46Z","receivedAt":"2007-05-18T03:37:46Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"Please pull from the maint branch at\n\n\tgit://linux-nfs.org/~bfields/git.git maint\n\nThis is mainly revisions of the patches posted a few days ago, which\nwere uncontraversial, so I won't resend them.  (They did need more\nproofreading than usual, though--thanks to everyone who helped!)\n\nOne final patch wasn't included before, so I'll follow up with that.\n\n--b.\n\n Documentation/glossary.txt                       |  228 +++--\n Documentation/howto/dangling-objects.txt         |  109 --\n Documentation/howto/isolate-bugs-with-bisect.txt |   65 --\n Documentation/howto/make-dist.txt                |   52 -\n Documentation/howto/using-topic-branches.txt     |  296 ------\n Documentation/user-manual.txt                    | 1192 +++++++++++++++++-----\n 6 files changed, 1046 insertions(+), 896 deletions(-)\n"},{"id":"42444","messageId":"20070518033916.GC30144@fieldses.org","threadId":"8197","inReplyTo":"20070518033746.GB30144@fieldses.org","subject":"[PATCH] user-manual: reorganize public git repo discussion","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-05-18T03:39:16Z","receivedAt":"2007-05-18T03:39:16Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"\nHelping a couple people set up public repos recently, I wanted to point\nthem at this piece of the user manual, but found it wasn't as helpful as\nit could be:\n\n\t- It starts with a big explanation of why you'd want a public\n\t  repository, not necessary in their case since they already knew\n\t  why they wanted that.  So, separate that out.\n\t- It skimps on some of the git-daemon details, and puts the http\n\t  export information first.  Fix that.\n\nAlso group all the public repo subsections into a single section, and do\nsome miscellaneous related editing.\n\nSigned-off-by: \"J. Bruce Fields\" <bfields@citi.umich.edu>\n---\n Documentation/user-manual.txt |   90 +++++++++++++++++++++++------------------\n 1 files changed, 50 insertions(+), 40 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 735fea1..f4843f4 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1674,31 +1674,30 @@ The final result will be a series of commits, one for each patch in\n the original mailbox, with authorship and commit log message each\n taken from the message containing each patch.\n \n-[[setting-up-a-public-repository]]\n-Setting up a public repository\n-------------------------------\n+[[public-repositories]]\n+Public git repositories\n+-----------------------\n \n-Another way to submit changes to a project is to simply tell the\n-maintainer of that project to pull from your repository, exactly as\n-you did in the section \"<<getting-updates-with-git-pull, Getting\n-updates with git pull>>\".\n+Another way to submit changes to a project is to tell the maintainer of\n+that project to pull the changes from your repository using git-pull[1].\n+In the section \"<<getting-updates-with-git-pull, Getting updates with\n+git pull>>\" we described this as a way to get updates from the \"main\"\n+repository, but it works just as well in the other direction.\n \n-If you and maintainer both have accounts on the same machine, then\n-then you can just pull changes from each other's repositories\n-directly; note that all of the commands (gitlink:git-clone[1],\n-git-fetch[1], git-pull[1], etc.) that accept a URL as an argument\n-will also accept a local directory name; so, for example, you can\n-use\n+If you and the maintainer both have accounts on the same machine, then\n+you can just pull changes from each other's repositories directly;\n+commands that accepts repository URLs as arguments will also accept a\n+local directory name:\n \n -------------------------------------------------\n $ git clone /path/to/repository\n $ git pull /path/to/other/repository\n -------------------------------------------------\n \n-If this sort of setup is inconvenient or impossible, another (more\n-common) option is to set up a public repository on a public server.\n-This also allows you to cleanly separate private work in progress\n-from publicly visible work.\n+However, the more common way to do this is to maintain a separate public\n+repository (usually on a different host) for others to pull changes\n+from.  This is usually more convenient, and allows you to cleanly\n+separate private work in progress from publicly visible work.\n \n You will continue to do your day-to-day work in your personal\n repository, but periodically \"push\" changes from your personal\n@@ -1717,32 +1716,52 @@ like this:\n         |               they push             V\n   their public repo <------------------- their repo\n \n-Now, assume your personal repository is in the directory ~/proj.  We\n-first create a new clone of the repository:\n+[[setting-up-a-public-repository]]\n+Setting up a public repository\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Assume your personal repository is in the directory ~/proj.  We\n+first create a new clone of the repository and tell git-daemon that it\n+is meant to be public:\n \n -------------------------------------------------\n $ git clone --bare ~/proj proj.git\n+$ touch proj.git/git-daemon-export-ok\n -------------------------------------------------\n \n The resulting directory proj.git contains a \"bare\" git repository--it is\n-just the contents of the \".git\" directory, without a checked-out copy of\n-a working directory.\n+just the contents of the \".git\" directory, without any files checked out\n+around it.\n \n Next, copy proj.git to the server where you plan to host the\n public repository.  You can use scp, rsync, or whatever is most\n convenient.\n \n-If somebody else maintains the public server, they may already have\n-set up a git service for you, and you may skip to the section\n+[[exporting-via-git]]\n+Exporting a git repository via the git protocol\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+This is the preferred method.\n+\n+If someone else administers the server, they should tell you what\n+directory to put the repository in, and what git:// url it will appear\n+at.  You can then skip to the section\n \"<<pushing-changes-to-a-public-repository,Pushing changes to a public\n repository>>\", below.\n \n-Otherwise, the following sections explain how to export your newly\n-created public repository:\n+Otherwise, all you need to do is start gitlink:git-daemon[1]; it will\n+listen on port 9418.  By default, it will allow access to any directory\n+that looks like a git directory and contains the magic file\n+git-daemon-export-ok.  Passing some directory paths as git-daemon\n+arguments will further restrict the exports to those paths.\n+\n+You can also run git-daemon as an inetd service; see the\n+gitlink:git-daemon[1] man page for details.  (See especially the\n+examples section.)\n \n [[exporting-via-http]]\n Exporting a git repository via http\n------------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n The git protocol gives better performance and reliability, but on a\n host with a web server set up, http exports may be simpler to set up.\n@@ -1774,20 +1793,11 @@ link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]\n for a slightly more sophisticated setup using WebDAV which also\n allows pushing over http.)\n \n-[[exporting-via-git]]\n-Exporting a git repository via the git protocol\n------------------------------------------------\n-\n-This is the preferred method.\n-\n-For now, we refer you to the gitlink:git-daemon[1] man page for\n-instructions.  (See especially the examples section.)\n-\n [[pushing-changes-to-a-public-repository]]\n Pushing changes to a public repository\n---------------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-Note that the two techniques outline above (exporting via\n+Note that the two techniques outlined above (exporting via\n <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other\n maintainers to fetch your latest changes, but they do not allow write\n access, which you will need to update the public repository with the\n@@ -1839,7 +1849,7 @@ details.\n \n [[setting-up-a-shared-repository]]\n Setting up a shared repository\n-------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Another way to collaborate is by using a model similar to that\n commonly used in CVS, where several developers with special rights\n@@ -1848,8 +1858,8 @@ link:cvs-migration.txt[git for CVS users] for instructions on how to\n set this up.\n \n [[setting-up-gitweb]]\n-Allow web browsing of a repository\n-----------------------------------\n+Allowing web browsing of a repository\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n The gitweb cgi script provides users an easy way to browse your\n project's files and history without having to install git; see the file\n-- \n1.5.1.4.19.g69e2\n"},{"id":"42446","messageId":"20070518045634.GU4489@pasky.or.cz","threadId":"8197","inReplyTo":"20070518033746.GB30144@fieldses.org","subject":"Re: Documentation (mainly user-manual) patches","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2007-05-18T04:56:35Z","receivedAt":"2007-05-18T04:56:35Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"  Hi,\n\nOn Fri, May 18, 2007 at 05:37:46AM CEST, J. Bruce Fields wrote:\n> Please pull from the maint branch at\n> \n> \tgit://linux-nfs.org/~bfields/git.git maint\n> \n> This is mainly revisions of the patches posted a few days ago, which\n> were uncontraversial, so I won't resend them.  (They did need more\n> proofreading than usual, though--thanks to everyone who helped!)\n> \n> One final patch wasn't included before, so I'll follow up with that.\n\n  BTW, there is this nice git-request-pull tool which will prepare this\nmail for you and additionally include the list of commits included in\nthat repository, which is somewhat more friendly to the readers (I\nmyself wondered). ;-)\n\n  Thanks,\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nEver try. Ever fail. No matter. // Try again. Fail again. Fail better.\n\t\t-- Samuel Beckett\n"},{"id":"42482","messageId":"20070518134316.GA21925@fieldses.org","threadId":"8197","inReplyTo":"20070518045634.GU4489@pasky.or.cz","subject":"Re: Documentation (mainly user-manual) patches","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-05-18T13:43:16Z","receivedAt":"2007-05-18T13:43:16Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, May 18, 2007 at 06:56:35AM +0200, Petr Baudis wrote:\n>   BTW, there is this nice git-request-pull tool which will prepare this\n> mail for you and additionally include the list of commits included in\n> that repository, which is somewhat more friendly to the readers (I\n> myself wondered). ;-)\n\nOK!  I'll start including the shortlog.  Appended, if anyone's still\ncurious about this one.--b.\n\nJ. Bruce Fields (10):\n      user-manual: revise birdseye-view chapter\n      glossary: expand and clarify some definitions, prune cross-references\n      user-manual: move quick-start to an appendix\n      Documentation: remove howto's now incorporated into manual\n      user-manual: move howto/make-dist.txt into user manual\n      user-manual: move howto/using-topic-branches into manual\n      user-manual: add a \"counting commits\" example\n      user-manual: introduce git\n      user-manual: listing commits reachable from some refs not others\n      user-manual: reorganize public git repo discussion\n\nJohannes Schindelin (1):\n      Add a birdview-on-the-source-code section to the user manual\n"},{"id":"42584","messageId":"20070519040212.GC3141@spearce.org","threadId":"8197","inReplyTo":"20070518134316.GA21925@fieldses.org","subject":"Re: Documentation (mainly user-manual) patches","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-05-19T04:02:12Z","receivedAt":"2007-05-19T04:02:12Z","isPatch":false,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"\"J. Bruce Fields\" <bfields@fieldses.org> wrote:\n> On Fri, May 18, 2007 at 06:56:35AM +0200, Petr Baudis wrote:\n> >   BTW, there is this nice git-request-pull tool which will prepare this\n> > mail for you and additionally include the list of commits included in\n> > that repository, which is somewhat more friendly to the readers (I\n> > myself wondered). ;-)\n> \n> OK!  I'll start including the shortlog.  Appended, if anyone's still\n> curious about this one.--b.\n\nrequest-pull also does nice things like include the fetch URL, and\nthe branch name, and in a nice format that makes it very easy to\ncopy and paste into a \"git pull\" (or \"git fetch\") command line[*1*],\nso its slightly more than just the shortlog.  ;-)\n\n\n[*1*] By popular demand from Git's creator.\n\n-- \nShawn.\n"},{"id":"42585","messageId":"20070519041357.GA2679@fieldses.org","threadId":"8197","inReplyTo":"20070519040212.GC3141@spearce.org","subject":"Re: Documentation (mainly user-manual) patches","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-05-19T04:13:57Z","receivedAt":"2007-05-19T04:13:57Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, May 19, 2007 at 12:02:12AM -0400, Shawn O. Pearce wrote:\n> request-pull also does nice things like include the fetch URL, and\n> the branch name, and in a nice format that makes it very easy to\n> copy and paste into a \"git pull\" (or \"git fetch\") command line[*1*],\n> so its slightly more than just the shortlog.  ;-)\n\nI know, but that's not hard to do by hand.  Which doesn't, of course,\nmean I won't screw it up....\n\nBut, actually, I tried it just now and it only gave the url:\n\n\tThe following changes since commit 164b19893ab5bc66b531a26480149a0dff082969:\n\t  Michael Hendricks (1):\n\t\tDocument core.excludesfile for git-add\n\n\tare found in the git repository at:\n\n\t\tgit://linux-nfs.org/~bfields/git.git\n\nHow's it supposed to figure out the branch name?  (And I'm not sure\nabout that \"change since commit...\" stuff--that seems like slight\noverkill.)\n\n--b.\n"},{"id":"42587","messageId":"20070519043234.GE3141@spearce.org","threadId":"8197","inReplyTo":"20070519041357.GA2679@fieldses.org","subject":"Re: Documentation (mainly user-manual) patches","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-05-19T04:32:34Z","receivedAt":"2007-05-19T04:32:34Z","isPatch":false,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"\"J. Bruce Fields\" <bfields@fieldses.org> wrote:\n> But, actually, I tried it just now and it only gave the url:\n> \n> \tThe following changes since commit 164b19893ab5bc66b531a26480149a0dff082969:\n> \t  Michael Hendricks (1):\n> \t\tDocument core.excludesfile for git-add\n> \n> \tare found in the git repository at:\n> \n> \t\tgit://linux-nfs.org/~bfields/git.git\n> \n> How's it supposed to figure out the branch name?\n\nIt connects to the remote URL, lists the refs found there, and\nfinds any that has the commit you passed in as the 3rd argument\n(defaults to HEAD).  If none match it prints ..BRANCH.NOT.VERIFIED..\nas the branch name, to signal no branch points at the given commit,\nwhich means it cannot be (easily) pulled.\n\nNot getting that means you have too old of a Git to have my branch\nimprovements.  It was in ff06c743dc, which is in master and hence\nshould be in 1.5.2 final.\n\n> (And I'm not sure\n> about that \"change since commit...\" stuff--that seems like slight\n> overkill.)\n\nYea, it can be a little overkill sometimes.  But the maintainer\nknows where you started from.  If that commit is horribly old he\nmight wonder what is going on.  ;-)\n\n-- \nShawn.\n"},{"id":"42589","messageId":"20070519051920.GB2679@fieldses.org","threadId":"8197","inReplyTo":"20070519043234.GE3141@spearce.org","subject":"Re: Documentation (mainly user-manual) patches","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-05-19T05:19:20Z","receivedAt":"2007-05-19T05:19:20Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, May 19, 2007 at 12:32:34AM -0400, Shawn O. Pearce wrote:\n> It connects to the remote URL, lists the refs found there, and\n> finds any that has the commit you passed in as the 3rd argument\n> (defaults to HEAD).  If none match it prints ..BRANCH.NOT.VERIFIED..\n> as the branch name, to signal no branch points at the given commit,\n> which means it cannot be (easily) pulled.\n> \n> Not getting that means you have too old of a Git to have my branch\n> improvements.  It was in ff06c743dc, which is in master and hence\n> should be in 1.5.2 final.\n\nOK, that's very nifty.\n\n> > (And I'm not sure\n> > about that \"change since commit...\" stuff--that seems like slight\n> > overkill.)\n> \n> Yea, it can be a little overkill sometimes.  But the maintainer\n> knows where you started from.  If that commit is horribly old he\n> might wonder what is going on.  ;-)\n\nIs that really helpful in practice?  Well, what would I know.\n\n--b.\n"}]}