{"thread":{"id":"37709","subject":"[PATCH v4 1/3] doc: modernise everyday.txt wording and format in man page style","startedAt":"2014-10-10T21:25:34Z","lastAt":"2014-10-11T10:09:24Z","messageCount":6,"participants":["Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":4,"patchTotal":3},"messages":[{"id":"250495","messageId":"1412976337-2476-1-git-send-email-philipoakley@iee.org","threadId":"37709","inReplyTo":null,"subject":"[PATCH v4 0/3] Make 'git help everyday' work","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-10T21:25:34Z","receivedAt":"2014-10-10T21:25:34Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This is hopefully the final revision of the patch...\nand integrates Junio's comments. \n\nI've eye-balled the man page and web page results, and corrected a few quote / back tick\nitems to be more consistent.\n\nRe: [PATCH v3 1/3] doc: modernise everyday.txt wording and format in man page style\nFrom: \"Junio C Hamano\" <gitster@pobox.com>\nSent: Tuesday, September 30, 2014 12:24 AM\nSubject: Re: [PATCH v3 1/3] doc: modernise everyday.txt wording and format in man page style\n> Philip Oakley <philipoakley@iee.org> writes:\n> \n>> @@ -45,7 +58,7 @@ following commands.\n>>  \n>>    * linkgit:git-rebase[1] to maintain topic branches.\n>>  \n>> -  * linkgit:git-tag[1] to mark known point.\n>> +  * linkgit:git-tag[1] to mark a known point.\n> \n> I really appreciate your attention to details here.\n> \n>> +<10> review commit logs; other forms to limit output can be\n>>  combined and include `--max-count=10` (show 10 commits),\n>>  `--until=2005-12-10`, etc.\n> \n> s/--max-count=//; perhaps?\nI've shown both in the update, as it's a help guide. How does it look?\n\n> \n>> @@ -131,27 +145,34 @@ Clone the upstream and work on it.  Feed changes to upstream.::\n>>  ------------\n>>  $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6\n>>  $ cd my2.6\n>> +$ git checkout -b mine master <1>\n>> +$ edit/compile/test; git commit -a -s <2>\n>> +$ git format-patch master <3>\n>> +$ git send-email --to=\"person <email@example.com>\" 00*.patch <4>\n>> +$ git pull <5>\n> \n> This may be found somewhat questionable by some people, as \"mine\"\n> does not build on the master at origin.  Insert \"git checkout master\"\n> before this step to cause <5> update the pristine copy of their\n> master, perhaps?  That way, the next step\nI'd misunderstood this initially (confusion as to build start point).\nI've added the checkout with a comment, and renumber those following.\n\n> \n>> +$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <6>\n> \n> starts making more sense.\n> \n>> +$ git fetch --tags <11>\n>> ...\n>> +<11> from time to time, obtain official tags from the `origin`\n>>  and store them under `.git/refs/tags/`.\n> \n> I am not sure if \"fetch --tags\" still needs to be taught, especially\n> in a \"quick guide\" document, because \"fetch\" has auto-followed\n> relevant tags for a long time since the original version of this\n> document was written.\nDone - removed.\n\n> \n>> +<3> arrange `git push` to push all local branches to\n>> +their corresponding branch of the mothership machine.\n>> +<4> push will stash all our work away on `remotes/satellite/*`\n>> +remote-tracking branches on the mothership machine.  You could use this\n>>  as a back-up method.\n> \n> The original mentions \"a back-up method\", but a larger benefit of\n> this kind of settings is that it lets you pretend that mothership\n> \"fetched\" from you.\n> \n> We may want to say \"You can use this to pretend as if the origin,\n> aka mothership, ran 'git fetch' from you, aka satellite\".  This is\n> especially true because the next step <5> is about how to integrate\n> your work done on 'satellite' into 'mothership' that cannot fetch\n> from 'satellite' (imagine satellite is behind a NAT and it can only\n> ssh out to mothership but not the other way around).\nText updated to include those points.\n\n> \n>> -Integrator[[Integrator]]\n>> +Integrator[[INTEGRATOR]]\n>>  ------------------------\n>>  \n>>  A fairly central person acting as the integrator in a group\n>> @@ -213,6 +235,9 @@ project receives changes made by others, reviews and integrates\n>>  them and publishes the result for others to use, using these\n>>  commands in addition to the ones needed by participants.\n>>  \n>> +This section can also be applied to a git-request-pull workflow,\n>> +or the GitHub (www.github.com) pull-request flow.\n> \n> Clarify which end of that workflow this can be applied, perhaps?\n> E.g. \"... also be used by the person who responds to 'git\n> request-pull' or pull-request on GitHub to integrate others' work\n> into your history\".\nSorted, as below.\n\n> \n> \n>> @@ -225,23 +250,26 @@ commands in addition to the ones needed by participants.\n>>  \n>>    * linkgit:git-push[1] to publish the bleeding edge.\n>>  \n>> +  * linkgit:git-request-pull[1] to create a summary of changes\n>> +    for your upstream to pull.\n>> +\n> \n> This new item looks somewhat out of place, doesn't it?  It is\n> because this is a participant item, not an integrator item.\nThe bullet item moved to Participant, and the text there updated.\n> \n> Yes, I know a sub-area lieutenant would request a pull by the\n> top-level maintainer, but when you interact with your 'upstream',\n> you are not acting as an integrator.\n> \n> If you really want to add request-pull to common 20-or-so commands,\n> it would make more sense to do so in the participant's section and\n> to explain that an sub-area lieutenant acts both as a participant\n> and as an integrator.\nAdded text in line with your comment.\n\n> \n> Thanks.\n\n--\n\nPhilip Oakley (3):\n  doc: modernise everyday.txt wording and format in man page style\n  doc: Makefile regularise OBSOLETE_HTML list building\n  Make 'git help everyday' work\n\n Documentation/Makefile             |   6 +-\n Documentation/everyday.txt         | 413 ---------------------------------\n Documentation/everyday.txto        |   9 +\n Documentation/git-push.txt         |   2 +-\n Documentation/git.txt              |   4 +-\n Documentation/gitcore-tutorial.txt |   2 +-\n Documentation/gitcvs-migration.txt |   2 +-\n Documentation/giteveryday.txt      | 455 +++++++++++++++++++++++++++++++++++++\n Documentation/gitglossary.txt      |   2 +-\n Documentation/gittutorial-2.txt    |   4 +-\n Documentation/gittutorial.txt      |   4 +-\n README                             |   2 +-\n builtin/help.c                     |   1 +\n 13 files changed, 480 insertions(+), 426 deletions(-)\n delete mode 100644 Documentation/everyday.txt\n create mode 100644 Documentation/everyday.txto\n create mode 100644 Documentation/giteveryday.txt\n\n-- \n1.9.4.msysgit.0\n"},{"id":"250494","messageId":"1412976337-2476-2-git-send-email-philipoakley@iee.org","threadId":"37709","inReplyTo":"1412976337-2476-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v4 1/3] doc: modernise everyday.txt wording and format in man page style","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-10T21:25:35Z","receivedAt":"2014-10-10T21:25:35Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Refresh the contents of everyday.txt contents to a more modern\ncommand style. Also update the mark-up so that it can be formatted\nas a man page with AsciiDoc ready for transfer to the Git guides.\nThe transfer is in subsequent commits.\n\nGuidance on modernising the command style provided by Junio at [1],\n[2] and [3].\n\n[1] Individual Developer, both Standalone and Participant\nhttp://article.gmane.org/gmane.comp.version-control.git/254269\n[2] Integrator\nhttp://article.gmane.org/gmane.comp.version-control.git/254502\n[3] Administrator\nhttp://article.gmane.org/gmane.comp.version-control.git/254824\n\nHelped-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n Documentation/everyday.txt | 260 ++++++++++++++++++++++++++-------------------\n 1 file changed, 151 insertions(+), 109 deletions(-)\n\ndiff --git a/Documentation/everyday.txt b/Documentation/everyday.txt\nindex b2548ef..97cecce 100644\n--- a/Documentation/everyday.txt\n+++ b/Documentation/everyday.txt\n@@ -1,22 +1,37 @@\n+giteveryday(7)\n+===============\n+\n+NAME\n+----\n+giteveryday - A useful minimum set of commands for Everyday Git\n+\n+SYNOPSIS\n+--------\n+\n Everyday Git With 20 Commands Or So\n-===================================\n \n-<<Individual Developer (Standalone)>> commands are essential for\n-anybody who makes a commit, even for somebody who works alone.\n+DESCRIPTION\n+-----------\n \n-If you work with other people, you will need commands listed in\n-the <<Individual Developer (Participant)>> section as well.\n+Git users can broadly be grouped into four categories for the purposes of\n+describing here a small set of useful command for everyday Git.\n \n-People who play the <<Integrator>> role need to learn some more\n-commands in addition to the above.\n+*\t<<STANDALONE,Individual Developer (Standalone)>> commands are essential\n+\tfor anybody who makes a commit, even for somebody who works alone.\n \n-<<Repository Administration>> commands are for system\n-administrators who are responsible for the care and feeding\n-of Git repositories.\n+*\tIf you work with other people, you will need commands listed in\n+\tthe <<PARTICIPANT,Individual Developer (Participant)>> section as well.\n \n+*\tPeople who play the <<INTEGRATOR,Integrator>> role need to learn some\n+\tmore commands in addition to the above.\n \n-Individual Developer (Standalone)[[Individual Developer (Standalone)]]\n-----------------------------------------------------------------------\n+*\t<<ADMINISTRATION,Repository Administration>> commands are for system\n+\tadministrators who are responsible for the care and feeding\n+\tof Git repositories.\n+\n+\n+Individual Developer (Standalone)[[STANDALONE]]\n+-----------------------------------------------\n \n A standalone individual developer does not exchange patches with\n other people, and works alone in a single repository, using the\n@@ -24,8 +39,6 @@ following commands.\n \n   * linkgit:git-init[1] to create a new repository.\n \n-  * linkgit:git-show-branch[1] to see where you are.\n-\n   * linkgit:git-log[1] to see what happened.\n \n   * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch\n@@ -45,7 +58,7 @@ following commands.\n \n   * linkgit:git-rebase[1] to maintain topic branches.\n \n-  * linkgit:git-tag[1] to mark known point.\n+  * linkgit:git-tag[1] to mark a known point.\n \n Examples\n ~~~~~~~~\n@@ -75,14 +88,12 @@ $ edit/compile/test\n $ git diff HEAD <4>\n $ git commit -a -s <5>\n $ edit/compile/test\n-$ git reset --soft HEAD^ <6>\n-$ edit/compile/test\n-$ git diff ORIG_HEAD <7>\n-$ git commit -a -c ORIG_HEAD <8>\n-$ git checkout master <9>\n-$ git merge alsa-audio <10>\n-$ git log --since='3 days ago' <11>\n-$ git log v2.43.. curses/ <12>\n+$ git diff HEAD^ <6>\n+$ git commit -a --amend <7>\n+$ git checkout master <8>\n+$ git merge alsa-audio <9>\n+$ git log --since='3 days ago' <10>\n+$ git log v2.43.. curses/ <11>\n ------------\n +\n <1> create a new topic branch.\n@@ -90,22 +101,21 @@ $ git log v2.43.. curses/ <12>\n <3> you need to tell Git if you added a new file; removal and\n modification will be caught if you do `git commit -a` later.\n <4> to see what changes you are committing.\n-<5> commit everything as you have tested, with your sign-off.\n-<6> take the last commit back, keeping what is in the working tree.\n-<7> look at the changes since the premature commit we took back.\n-<8> redo the commit undone in the previous step, using the message\n-you originally wrote.\n-<9> switch to the master branch.\n-<10> merge a topic branch into your master branch.\n-<11> review commit logs; other forms to limit output can be\n-combined and include `--max-count=10` (show 10 commits),\n+<5> commit everything, as you have tested, with your sign-off.\n+<6> look at all your changes including the previous commit.\n+<7> amend the previous commit, adding all your new changes,\n+using your original message.\n+<8> switch to the master branch.\n+<9> merge a topic branch into your master branch.\n+<10> review commit logs; other forms to limit output can be\n+combined and include `10` (equiv. `--max-count=10`, to show 10 commits),\n `--until=2005-12-10`, etc.\n-<12> view only the changes that touch what's in `curses/`\n+<11> view only the changes that touch what's in `curses/`\n directory, since `v2.43` tag.\n \n \n-Individual Developer (Participant)[[Individual Developer (Participant)]]\n-------------------------------------------------------------------------\n+Individual Developer (Participant)[[PARTICIPANT]]\n+-------------------------------------------------\n \n A developer working as a participant in a group project needs to\n learn how to communicate with others, and uses these commands in\n@@ -123,6 +133,13 @@ addition to the ones needed by a standalone developer.\n   * linkgit:git-format-patch[1] to prepare e-mail submission, if\n     you adopt Linux kernel-style public forum workflow.\n \n+  * linkgit:git-send-email[1] to send your e-mail submission without\n+    corruption by your MUA.\n+\n+  * linkgit:git-request-pull[1] to create a summary of changes\n+    for your upstream to pull.\n+\n+\n Examples\n ~~~~~~~~\n \n@@ -131,28 +148,34 @@ Clone the upstream and work on it.  Feed changes to upstream.::\n ------------\n $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6\n $ cd my2.6\n-$ edit/compile/test; git commit -a -s <1>\n-$ git format-patch origin <2>\n-$ git pull <3>\n-$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>\n-$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>\n-$ git reset --hard ORIG_HEAD <6>\n-$ git gc <7>\n-$ git fetch --tags <8>\n+$ git checkout -b mine master <1>\n+$ edit/compile/test; git commit -a -s <2>\n+$ git format-patch master <3>\n+$ git send-email --to=\"person <email@example.com>\" 00*.patch <4>\n+$ git checkout master <5>\n+$ git pull <6>\n+$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>\n+$ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>\n+$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <9>\n+$ git reset --hard ORIG_HEAD <10>\n+$ git gc <11>\n ------------\n +\n-<1> repeat as needed.\n-<2> extract patches from your branch for e-mail submission.\n-<3> `git pull` fetches from `origin` by default and merges into the\n+<1> checkout a new branch `mine` from master.\n+<2> repeat as needed.\n+<3> extract patches from your branch, relative to master,\n+<4> and email them.\n+<5> return to `master`, ready to see what's new\n+<6> `git pull` fetches from `origin` by default and merges into the\n current branch.\n-<4> immediately after pulling, look at the changes done upstream\n+<7> immediately after pulling, look at the changes done upstream\n since last time we checked, only in the\n area we are interested in.\n-<5> fetch from a specific branch from a specific repository and merge.\n-<6> revert the pull.\n-<7> garbage collect leftover objects from reverted pull.\n-<8> from time to time, obtain official tags from the `origin`\n-and store them under `.git/refs/tags/`.\n+<8> check the branch names in an external repository (if not known).\n+<9> fetch from a specific branch `ALL` from a specific repository\n+and merge it.\n+<10> revert the pull.\n+<11> garbage collect leftover objects from reverted pull.\n \n \n Push into another repository.::\n@@ -166,7 +189,7 @@ remote.origin.fetch refs/heads/*:refs/remotes/origin/*\n branch.master.remote origin\n branch.master.merge refs/heads/master\n satellite$ git config remote.origin.push \\\n-           master:refs/remotes/satellite/master <3>\n+           +refs/heads/*:refs/remotes/satellite/* <3>\n satellite$ edit/compile/test/commit\n satellite$ git push origin <4>\n \n@@ -181,11 +204,12 @@ machine.\n <2> clone sets these configuration variables by default.\n It arranges `git pull` to fetch and store the branches of mothership\n machine to local `remotes/origin/*` remote-tracking branches.\n-<3> arrange `git push` to push local `master` branch to\n-`remotes/satellite/master` branch of the mothership machine.\n-<4> push will stash our work away on `remotes/satellite/master`\n-remote-tracking branch on the mothership machine.  You could use this\n-as a back-up method.\n+<3> arrange `git push` to push all local branches to\n+their corresponding branch of the mothership machine.\n+<4> push will stash all our work away on `remotes/satellite/*`\n+remote-tracking branches on the mothership machine.  You could use this\n+as a back-up method. Likewise, you can pretend that mothership\n+\"fetched\" from you (useful when access is one sided).\n <5> on mothership machine, merge the work done on the satellite\n machine into the master branch.\n \n@@ -195,17 +219,22 @@ Branch off of a specific tag.::\n $ git checkout -b private2.6.14 v2.6.14 <1>\n $ edit/compile/test; git commit -a\n $ git checkout master\n-$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |\n-  git am -3 -k <2>\n+$ git cherry-pick v2.6.14..private2.6.14 <2>\n ------------\n +\n <1> create a private branch based on a well known (but somewhat behind)\n tag.\n <2> forward port all changes in `private2.6.14` branch to `master` branch\n-without a formal \"merging\".\n+without a formal \"merging\". Or longhand +\n+`git format-patch -k -m --stdout v2.6.14..private2.6.14 |\n+  git am -3 -k`\n \n+An alternate participant submission mechanism is using the\n+`git request-pull` or pull-request mechanisms (e.g as used on\n+GitHub (www.github.com) to notify your upstream of your\n+contribution.\n \n-Integrator[[Integrator]]\n+Integrator[[INTEGRATOR]]\n ------------------------\n \n A fairly central person acting as the integrator in a group\n@@ -213,6 +242,13 @@ project receives changes made by others, reviews and integrates\n them and publishes the result for others to use, using these\n commands in addition to the ones needed by participants.\n \n+This section can also be used by those who respond to `git\n+request-pull` or pull-request on GitHub (www.github.com) to\n+integrate the work of others into their history. An sub-area\n+lieutenant for a repository will act both as a participant and\n+as an integrator.\n+\n+\n   * linkgit:git-am[1] to apply patches e-mailed in from your\n     contributors.\n \n@@ -229,19 +265,19 @@ commands in addition to the ones needed by participants.\n Examples\n ~~~~~~~~\n \n-My typical Git day.::\n+A typical integrator's Git day.::\n +\n ------------\n $ git status <1>\n-$ git show-branch <2>\n+$ git branch --no-merged master <2>\n $ mailx <3>\n & s 2 3 4 5 ./+to-apply\n & s 7 8 ./+hold-linus\n & q\n $ git checkout -b topic/one master\n-$ git am -3 -i -s -u ./+to-apply <4>\n+$ git am -3 -i -s ./+to-apply <4>\n $ compile/test\n-$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>\n+$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5>\n $ git checkout topic/one && git rebase master <6>\n $ git checkout pu && git reset --hard next <7>\n $ git merge topic/one topic/two && git merge hold/linus <8>\n@@ -249,51 +285,51 @@ $ git checkout maint\n $ git cherry-pick master~4 <9>\n $ compile/test\n $ git tag -s -m \"GIT 0.99.9x\" v0.99.9x <10>\n-$ git fetch ko && git show-branch master maint 'tags/ko-*' <11>\n-$ git push ko <12>\n-$ git push ko v0.99.9x <13>\n+$ git fetch ko && for branch in master maint next pu <11>\n+    do\n+        git show-branch ko/$branch $branch <12>\n+    done\n+$ git push --follow-tags ko <13>\n ------------\n +\n-<1> see what I was in the middle of doing, if any.\n-<2> see what topic branches I have and think about how ready\n-they are.\n+<1> see what you were in the middle of doing, if anything.\n+<2> see which branches haven't been merged into `master` yet.\n+Likewise for any other integration branches e.g. `maint`, `next`\n+and `pu` (potential updates).\n <3> read mails, save ones that are applicable, and save others\n-that are not quite ready.\n-<4> apply them, interactively, with my sign-offs.\n-<5> create topic branch as needed and apply, again with my\n-sign-offs.\n+that are not quite ready (other mail readers are available).\n+<4> apply them, interactively, with your sign-offs.\n+<5> create topic branch as needed and apply, again with sign-offs.\n <6> rebase internal topic branch that has not been merged to the\n master or exposed as a part of a stable branch.\n <7> restart `pu` every time from the next.\n <8> and bundle topic branches still cooking.\n <9> backport a critical fix.\n <10> create a signed tag.\n-<11> make sure I did not accidentally rewind master beyond what I\n-already pushed out.  `ko` shorthand points at the repository I have\n-at kernel.org, and looks like this:\n+<11> make sure master was not accidentally rewound beyond that\n+already pushed out.  `ko` shorthand points at the Git maintainer's\n+repository at kernel.org, and looks like this:\n +\n ------------\n-$ cat .git/remotes/ko\n-URL: kernel.org:/pub/scm/git/git.git\n-Pull: master:refs/tags/ko-master\n-Pull: next:refs/tags/ko-next\n-Pull: maint:refs/tags/ko-maint\n-Push: master\n-Push: next\n-Push: +pu\n-Push: maint\n+(in .git/config)\n+[remote \"ko\"]\n+        url = kernel.org:/pub/scm/git/git.git\n+        fetch = refs/heads/*:refs/remotes/ko/*\n+        push = refs/heads/master\n+        push = refs/heads/next\n+        push = +refs/heads/pu\n+        push = refs/heads/maint\n ------------\n +\n-In the output from `git show-branch`, `master` should have\n-everything `ko-master` has, and `next` should have\n-everything `ko-next` has.\n-\n-<12> push out the bleeding edge.\n-<13> push the tag out, too.\n+<12> In the output from `git show-branch`, `master` should have\n+everything `ko/master` has, and `next` should have\n+everything `ko/next` has, etc.\n+<13> push out the bleeding edge, together with new tags that point\n+into the pushed history.\n \n \n-Repository Administration[[Repository Administration]]\n-------------------------------------------------------\n+Repository Administration[[ADMINISTRATION]]\n+-------------------------------------------\n \n A repository administrator uses the following tools to set up\n and maintain access to the repository by developers.\n@@ -304,9 +340,19 @@ and maintain access to the repository by developers.\n   * linkgit:git-shell[1] can be used as a 'restricted login shell'\n     for shared central repository users.\n \n+  * linkgit:git-http-backend[1] provides a server side implementation\n+    of Git-over-HTTP (\"Smart http\") allowing both fetch and push services.\n+\n+  * linkgit:gitweb[1] provides a web front-end to Git repositories,\n+    which can be set-up using the linkgit:git-instaweb[1] script.\n+\n link:howto/update-hook-example.html[update hook howto] has a good\n example of managing a shared central repository.\n \n+In addition there are a number of other widely deployed hosting, browsing\n+and reviewing solutions such as:\n+\n+  * gitolite, gerrit code review, cgit and others.\n \n Examples\n ~~~~~~~~\n@@ -350,7 +396,10 @@ service git\n Check your xinetd(8) documentation and setup, this is from a Fedora system.\n Others might be different.\n \n-Give push/pull only access to developers.::\n+Give push/pull only access to developers using git-over-ssh.::\n+\n+e.g. those using:\n+`$ git push/pull ssh://host.xz/pub/scm/project`\n +\n ------------\n $ grep git /etc/passwd <1>\n@@ -363,8 +412,8 @@ $ grep git /etc/shells <2>\n ------------\n +\n <1> log-in shell is set to /usr/bin/git-shell, which does not\n-allow anything but `git push` and `git pull`.  The users should\n-get an ssh access to the machine.\n+allow anything but `git push` and `git pull`.  The users require\n+ssh access to the machine.\n <2> in many distributions /etc/shells needs to list what is used\n as the login shell.\n \n@@ -401,13 +450,6 @@ for branch policy control.\n david is the release manager and is the only person who can\n create and push version tags.\n \n-HTTP server to support dumb protocol transfer.::\n-+\n-------------\n-dev$ git update-server-info <1>\n-dev$ ftp user@isp.example.com <2>\n-ftp> cp -r .git /home/user/myproject.git\n-------------\n-+\n-<1> make sure your info/refs and objects/info/packs are up-to-date\n-<2> upload to public HTTP server hosted by your ISP.\n+GIT\n+---\n+Part of the linkgit:git[1] suite\n-- \n1.9.4.msysgit.0\n"},{"id":"250497","messageId":"1412976337-2476-3-git-send-email-philipoakley@iee.org","threadId":"37709","inReplyTo":"1412976337-2476-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v4 2/3] doc: Makefile regularise OBSOLETE_HTML list building","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-10T21:25:36Z","receivedAt":"2014-10-10T21:25:36Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Helped-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n Documentation/Makefile | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cea0e7a..3b56714 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -5,6 +5,7 @@ MAN7_TXT =\n TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n+OBSOLETE_HTML =\n \n MAN1_TXT += $(filter-out \\\n \t\t$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \\\n@@ -37,7 +38,7 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))\n MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))\n \n-OBSOLETE_HTML = git-remote-helpers.html\n+OBSOLETE_HTML += git-remote-helpers.html\n DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)\n \n ARTICLES += howto-index\n-- \n1.9.4.msysgit.0\n"},{"id":"250496","messageId":"1412976337-2476-4-git-send-email-philipoakley@iee.org","threadId":"37709","inReplyTo":"1412976337-2476-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v4 3/3] Make 'git help everyday' work","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-10T21:25:37Z","receivedAt":"2014-10-10T21:25:37Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The \"Everyday GIT With 20 Commands Or So\" is not accessible via the\nGit help system.  Move everyday.txt to giteveryday.txt so that \"git\nhelp everyday\" works, and create a new placeholder file everyday.html\nto refer people who follow existing URLs to the updated location.\n\ngiteveryday.txt now formats well with AsciiDoc as a man page and\nrefreshed content to a more command modern style.\n\nAdd 'everyday' to the help --guides list and update git(1) and 5\nother links to giteveryday.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.org>\n---\n Documentation/Makefile             |   3 +-\n Documentation/everyday.txt         | 455 -------------------------------------\n Documentation/everyday.txto        |   9 +\n Documentation/git-push.txt         |   2 +-\n Documentation/git.txt              |   4 +-\n Documentation/gitcore-tutorial.txt |   2 +-\n Documentation/gitcvs-migration.txt |   2 +-\n Documentation/giteveryday.txt      | 455 +++++++++++++++++++++++++++++++++++++\n Documentation/gitglossary.txt      |   2 +-\n Documentation/gittutorial-2.txt    |   4 +-\n Documentation/gittutorial.txt      |   4 +-\n README                             |   2 +-\n builtin/help.c                     |   1 +\n 13 files changed, 478 insertions(+), 467 deletions(-)\n delete mode 100644 Documentation/everyday.txt\n create mode 100644 Documentation/everyday.txto\n create mode 100644 Documentation/giteveryday.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3b56714..8d0f709 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -27,6 +27,7 @@ MAN7_TXT += gitcore-tutorial.txt\n MAN7_TXT += gitcredentials.txt\n MAN7_TXT += gitcvs-migration.txt\n MAN7_TXT += gitdiffcore.txt\n+MAN7_TXT += giteveryday.txt\n MAN7_TXT += gitglossary.txt\n MAN7_TXT += gitnamespaces.txt\n MAN7_TXT += gitrevisions.txt\n@@ -38,11 +39,11 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))\n MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))\n \n+OBSOLETE_HTML += everyday.html\n OBSOLETE_HTML += git-remote-helpers.html\n DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)\n \n ARTICLES += howto-index\n-ARTICLES += everyday\n ARTICLES += git-tools\n ARTICLES += git-bisect-lk2009\n # with their own formatting rules.\ndiff --git a/Documentation/everyday.txt b/Documentation/everyday.txt\ndeleted file mode 100644\nindex 97cecce..0000000\n--- a/Documentation/everyday.txt\n+++ /dev/null\n@@ -1,455 +0,0 @@\n-giteveryday(7)\n-===============\n-\n-NAME\n-----\n-giteveryday - A useful minimum set of commands for Everyday Git\n-\n-SYNOPSIS\n---------\n-\n-Everyday Git With 20 Commands Or So\n-\n-DESCRIPTION\n------------\n-\n-Git users can broadly be grouped into four categories for the purposes of\n-describing here a small set of useful command for everyday Git.\n-\n-*\t<<STANDALONE,Individual Developer (Standalone)>> commands are essential\n-\tfor anybody who makes a commit, even for somebody who works alone.\n-\n-*\tIf you work with other people, you will need commands listed in\n-\tthe <<PARTICIPANT,Individual Developer (Participant)>> section as well.\n-\n-*\tPeople who play the <<INTEGRATOR,Integrator>> role need to learn some\n-\tmore commands in addition to the above.\n-\n-*\t<<ADMINISTRATION,Repository Administration>> commands are for system\n-\tadministrators who are responsible for the care and feeding\n-\tof Git repositories.\n-\n-\n-Individual Developer (Standalone)[[STANDALONE]]\n------------------------------------------------\n-\n-A standalone individual developer does not exchange patches with\n-other people, and works alone in a single repository, using the\n-following commands.\n-\n-  * linkgit:git-init[1] to create a new repository.\n-\n-  * linkgit:git-log[1] to see what happened.\n-\n-  * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch\n-    branches.\n-\n-  * linkgit:git-add[1] to manage the index file.\n-\n-  * linkgit:git-diff[1] and linkgit:git-status[1] to see what\n-    you are in the middle of doing.\n-\n-  * linkgit:git-commit[1] to advance the current branch.\n-\n-  * linkgit:git-reset[1] and linkgit:git-checkout[1] (with\n-    pathname parameters) to undo changes.\n-\n-  * linkgit:git-merge[1] to merge between local branches.\n-\n-  * linkgit:git-rebase[1] to maintain topic branches.\n-\n-  * linkgit:git-tag[1] to mark a known point.\n-\n-Examples\n-~~~~~~~~\n-\n-Use a tarball as a starting point for a new repository.::\n-+\n-------------\n-$ tar zxf frotz.tar.gz\n-$ cd frotz\n-$ git init\n-$ git add . <1>\n-$ git commit -m \"import of frotz source tree.\"\n-$ git tag v2.43 <2>\n-------------\n-+\n-<1> add everything under the current directory.\n-<2> make a lightweight, unannotated tag.\n-\n-Create a topic branch and develop.::\n-+\n-------------\n-$ git checkout -b alsa-audio <1>\n-$ edit/compile/test\n-$ git checkout -- curses/ux_audio_oss.c <2>\n-$ git add curses/ux_audio_alsa.c <3>\n-$ edit/compile/test\n-$ git diff HEAD <4>\n-$ git commit -a -s <5>\n-$ edit/compile/test\n-$ git diff HEAD^ <6>\n-$ git commit -a --amend <7>\n-$ git checkout master <8>\n-$ git merge alsa-audio <9>\n-$ git log --since='3 days ago' <10>\n-$ git log v2.43.. curses/ <11>\n-------------\n-+\n-<1> create a new topic branch.\n-<2> revert your botched changes in `curses/ux_audio_oss.c`.\n-<3> you need to tell Git if you added a new file; removal and\n-modification will be caught if you do `git commit -a` later.\n-<4> to see what changes you are committing.\n-<5> commit everything, as you have tested, with your sign-off.\n-<6> look at all your changes including the previous commit.\n-<7> amend the previous commit, adding all your new changes,\n-using your original message.\n-<8> switch to the master branch.\n-<9> merge a topic branch into your master branch.\n-<10> review commit logs; other forms to limit output can be\n-combined and include `10` (equiv. `--max-count=10`, to show 10 commits),\n-`--until=2005-12-10`, etc.\n-<11> view only the changes that touch what's in `curses/`\n-directory, since `v2.43` tag.\n-\n-\n-Individual Developer (Participant)[[PARTICIPANT]]\n--------------------------------------------------\n-\n-A developer working as a participant in a group project needs to\n-learn how to communicate with others, and uses these commands in\n-addition to the ones needed by a standalone developer.\n-\n-  * linkgit:git-clone[1] from the upstream to prime your local\n-    repository.\n-\n-  * linkgit:git-pull[1] and linkgit:git-fetch[1] from \"origin\"\n-    to keep up-to-date with the upstream.\n-\n-  * linkgit:git-push[1] to shared repository, if you adopt CVS\n-    style shared repository workflow.\n-\n-  * linkgit:git-format-patch[1] to prepare e-mail submission, if\n-    you adopt Linux kernel-style public forum workflow.\n-\n-  * linkgit:git-send-email[1] to send your e-mail submission without\n-    corruption by your MUA.\n-\n-  * linkgit:git-request-pull[1] to create a summary of changes\n-    for your upstream to pull.\n-\n-\n-Examples\n-~~~~~~~~\n-\n-Clone the upstream and work on it.  Feed changes to upstream.::\n-+\n-------------\n-$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6\n-$ cd my2.6\n-$ git checkout -b mine master <1>\n-$ edit/compile/test; git commit -a -s <2>\n-$ git format-patch master <3>\n-$ git send-email --to=\"person <email@example.com>\" 00*.patch <4>\n-$ git checkout master <5>\n-$ git pull <6>\n-$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>\n-$ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>\n-$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <9>\n-$ git reset --hard ORIG_HEAD <10>\n-$ git gc <11>\n-------------\n-+\n-<1> checkout a new branch `mine` from master.\n-<2> repeat as needed.\n-<3> extract patches from your branch, relative to master,\n-<4> and email them.\n-<5> return to `master`, ready to see what's new\n-<6> `git pull` fetches from `origin` by default and merges into the\n-current branch.\n-<7> immediately after pulling, look at the changes done upstream\n-since last time we checked, only in the\n-area we are interested in.\n-<8> check the branch names in an external repository (if not known).\n-<9> fetch from a specific branch `ALL` from a specific repository\n-and merge it.\n-<10> revert the pull.\n-<11> garbage collect leftover objects from reverted pull.\n-\n-\n-Push into another repository.::\n-+\n-------------\n-satellite$ git clone mothership:frotz frotz <1>\n-satellite$ cd frotz\n-satellite$ git config --get-regexp '^(remote|branch)\\.' <2>\n-remote.origin.url mothership:frotz\n-remote.origin.fetch refs/heads/*:refs/remotes/origin/*\n-branch.master.remote origin\n-branch.master.merge refs/heads/master\n-satellite$ git config remote.origin.push \\\n-           +refs/heads/*:refs/remotes/satellite/* <3>\n-satellite$ edit/compile/test/commit\n-satellite$ git push origin <4>\n-\n-mothership$ cd frotz\n-mothership$ git checkout master\n-mothership$ git merge satellite/master <5>\n-------------\n-+\n-<1> mothership machine has a frotz repository under your home\n-directory; clone from it to start a repository on the satellite\n-machine.\n-<2> clone sets these configuration variables by default.\n-It arranges `git pull` to fetch and store the branches of mothership\n-machine to local `remotes/origin/*` remote-tracking branches.\n-<3> arrange `git push` to push all local branches to\n-their corresponding branch of the mothership machine.\n-<4> push will stash all our work away on `remotes/satellite/*`\n-remote-tracking branches on the mothership machine.  You could use this\n-as a back-up method. Likewise, you can pretend that mothership\n-\"fetched\" from you (useful when access is one sided).\n-<5> on mothership machine, merge the work done on the satellite\n-machine into the master branch.\n-\n-Branch off of a specific tag.::\n-+\n-------------\n-$ git checkout -b private2.6.14 v2.6.14 <1>\n-$ edit/compile/test; git commit -a\n-$ git checkout master\n-$ git cherry-pick v2.6.14..private2.6.14 <2>\n-------------\n-+\n-<1> create a private branch based on a well known (but somewhat behind)\n-tag.\n-<2> forward port all changes in `private2.6.14` branch to `master` branch\n-without a formal \"merging\". Or longhand +\n-`git format-patch -k -m --stdout v2.6.14..private2.6.14 |\n-  git am -3 -k`\n-\n-An alternate participant submission mechanism is using the\n-`git request-pull` or pull-request mechanisms (e.g as used on\n-GitHub (www.github.com) to notify your upstream of your\n-contribution.\n-\n-Integrator[[INTEGRATOR]]\n-------------------------\n-\n-A fairly central person acting as the integrator in a group\n-project receives changes made by others, reviews and integrates\n-them and publishes the result for others to use, using these\n-commands in addition to the ones needed by participants.\n-\n-This section can also be used by those who respond to `git\n-request-pull` or pull-request on GitHub (www.github.com) to\n-integrate the work of others into their history. An sub-area\n-lieutenant for a repository will act both as a participant and\n-as an integrator.\n-\n-\n-  * linkgit:git-am[1] to apply patches e-mailed in from your\n-    contributors.\n-\n-  * linkgit:git-pull[1] to merge from your trusted lieutenants.\n-\n-  * linkgit:git-format-patch[1] to prepare and send suggested\n-    alternative to contributors.\n-\n-  * linkgit:git-revert[1] to undo botched commits.\n-\n-  * linkgit:git-push[1] to publish the bleeding edge.\n-\n-\n-Examples\n-~~~~~~~~\n-\n-A typical integrator's Git day.::\n-+\n-------------\n-$ git status <1>\n-$ git branch --no-merged master <2>\n-$ mailx <3>\n-& s 2 3 4 5 ./+to-apply\n-& s 7 8 ./+hold-linus\n-& q\n-$ git checkout -b topic/one master\n-$ git am -3 -i -s ./+to-apply <4>\n-$ compile/test\n-$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5>\n-$ git checkout topic/one && git rebase master <6>\n-$ git checkout pu && git reset --hard next <7>\n-$ git merge topic/one topic/two && git merge hold/linus <8>\n-$ git checkout maint\n-$ git cherry-pick master~4 <9>\n-$ compile/test\n-$ git tag -s -m \"GIT 0.99.9x\" v0.99.9x <10>\n-$ git fetch ko && for branch in master maint next pu <11>\n-    do\n-        git show-branch ko/$branch $branch <12>\n-    done\n-$ git push --follow-tags ko <13>\n-------------\n-+\n-<1> see what you were in the middle of doing, if anything.\n-<2> see which branches haven't been merged into `master` yet.\n-Likewise for any other integration branches e.g. `maint`, `next`\n-and `pu` (potential updates).\n-<3> read mails, save ones that are applicable, and save others\n-that are not quite ready (other mail readers are available).\n-<4> apply them, interactively, with your sign-offs.\n-<5> create topic branch as needed and apply, again with sign-offs.\n-<6> rebase internal topic branch that has not been merged to the\n-master or exposed as a part of a stable branch.\n-<7> restart `pu` every time from the next.\n-<8> and bundle topic branches still cooking.\n-<9> backport a critical fix.\n-<10> create a signed tag.\n-<11> make sure master was not accidentally rewound beyond that\n-already pushed out.  `ko` shorthand points at the Git maintainer's\n-repository at kernel.org, and looks like this:\n-+\n-------------\n-(in .git/config)\n-[remote \"ko\"]\n-        url = kernel.org:/pub/scm/git/git.git\n-        fetch = refs/heads/*:refs/remotes/ko/*\n-        push = refs/heads/master\n-        push = refs/heads/next\n-        push = +refs/heads/pu\n-        push = refs/heads/maint\n-------------\n-+\n-<12> In the output from `git show-branch`, `master` should have\n-everything `ko/master` has, and `next` should have\n-everything `ko/next` has, etc.\n-<13> push out the bleeding edge, together with new tags that point\n-into the pushed history.\n-\n-\n-Repository Administration[[ADMINISTRATION]]\n--------------------------------------------\n-\n-A repository administrator uses the following tools to set up\n-and maintain access to the repository by developers.\n-\n-  * linkgit:git-daemon[1] to allow anonymous download from\n-    repository.\n-\n-  * linkgit:git-shell[1] can be used as a 'restricted login shell'\n-    for shared central repository users.\n-\n-  * linkgit:git-http-backend[1] provides a server side implementation\n-    of Git-over-HTTP (\"Smart http\") allowing both fetch and push services.\n-\n-  * linkgit:gitweb[1] provides a web front-end to Git repositories,\n-    which can be set-up using the linkgit:git-instaweb[1] script.\n-\n-link:howto/update-hook-example.html[update hook howto] has a good\n-example of managing a shared central repository.\n-\n-In addition there are a number of other widely deployed hosting, browsing\n-and reviewing solutions such as:\n-\n-  * gitolite, gerrit code review, cgit and others.\n-\n-Examples\n-~~~~~~~~\n-We assume the following in /etc/services::\n-+\n-------------\n-$ grep 9418 /etc/services\n-git\t\t9418/tcp\t\t# Git Version Control System\n-------------\n-\n-Run git-daemon to serve /pub/scm from inetd.::\n-+\n-------------\n-$ grep git /etc/inetd.conf\n-git\tstream\ttcp\tnowait\tnobody \\\n-  /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm\n-------------\n-+\n-The actual configuration line should be on one line.\n-\n-Run git-daemon to serve /pub/scm from xinetd.::\n-+\n-------------\n-$ cat /etc/xinetd.d/git-daemon\n-# default: off\n-# description: The Git server offers access to Git repositories\n-service git\n-{\n-        disable = no\n-        type            = UNLISTED\n-        port            = 9418\n-        socket_type     = stream\n-        wait            = no\n-        user            = nobody\n-        server          = /usr/bin/git-daemon\n-        server_args     = --inetd --export-all --base-path=/pub/scm\n-        log_on_failure  += USERID\n-}\n-------------\n-+\n-Check your xinetd(8) documentation and setup, this is from a Fedora system.\n-Others might be different.\n-\n-Give push/pull only access to developers using git-over-ssh.::\n-\n-e.g. those using:\n-`$ git push/pull ssh://host.xz/pub/scm/project`\n-+\n-------------\n-$ grep git /etc/passwd <1>\n-alice:x:1000:1000::/home/alice:/usr/bin/git-shell\n-bob:x:1001:1001::/home/bob:/usr/bin/git-shell\n-cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell\n-david:x:1003:1003::/home/david:/usr/bin/git-shell\n-$ grep git /etc/shells <2>\n-/usr/bin/git-shell\n-------------\n-+\n-<1> log-in shell is set to /usr/bin/git-shell, which does not\n-allow anything but `git push` and `git pull`.  The users require\n-ssh access to the machine.\n-<2> in many distributions /etc/shells needs to list what is used\n-as the login shell.\n-\n-CVS-style shared repository.::\n-+\n-------------\n-$ grep git /etc/group <1>\n-git:x:9418:alice,bob,cindy,david\n-$ cd /home/devo.git\n-$ ls -l <2>\n-  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master\n-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches\n-  -rw-rw-r--   1 david git    84 Dec  4 22:40 config\n-  -rw-rw-r--   1 david git    58 Dec  4 22:40 description\n-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks\n-  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index\n-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info\n-  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects\n-  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs\n-  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes\n-$ ls -l hooks/update <3>\n-  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update\n-$ cat info/allowed-users <4>\n-refs/heads/master\talice\\|cindy\n-refs/heads/doc-update\tbob\n-refs/tags/v[0-9]*\tdavid\n-------------\n-+\n-<1> place the developers into the same git group.\n-<2> and make the shared repository writable by the group.\n-<3> use update-hook example by Carl from Documentation/howto/\n-for branch policy control.\n-<4> alice and cindy can push into master, only bob can push into doc-update.\n-david is the release manager and is the only person who can\n-create and push version tags.\n-\n-GIT\n----\n-Part of the linkgit:git[1] suite\ndiff --git a/Documentation/everyday.txto b/Documentation/everyday.txto\nnew file mode 100644\nindex 0000000..c5047d8\n--- /dev/null\n+++ b/Documentation/everyday.txto\n@@ -0,0 +1,9 @@\n+Everyday Git With 20 Commands Or So\n+===================================\n+\n+This document has been moved to linkgit:giteveryday[1].\n+\n+Please let the owners of the referring site know so that they can update the\n+link you clicked to get here.\n+\n+Thanks.\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex b17283a..21b3f29 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -34,7 +34,7 @@ When the command line does not specify what to push with `<refspec>...`\n arguments or `--all`, `--mirror`, `--tags` options, the command finds\n the default `<refspec>` by consulting `remote.*.push` configuration,\n and if it is not found, honors `push.default` configuration to decide\n-what to push (See linkgit:git-config[1] for the meaning of `push.default`).\n+what to push (See gitlink:git-config[1] for the meaning of `push.default`).\n \n \n OPTIONS[[OPTIONS]]\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex c6175d4..9e0a42c 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -22,7 +22,7 @@ unusually rich command set that provides both high-level operations\n and full access to internals.\n \n See linkgit:gittutorial[7] to get started, then see\n-link:everyday.html[Everyday Git] for a useful minimum set of\n+linkgit:giteveryday[7] for a useful minimum set of\n commands.  The link:user-manual.html[Git User's Manual] has a more\n in-depth introduction.\n \n@@ -1098,7 +1098,7 @@ subscribed to the list to send a message there.\n SEE ALSO\n --------\n linkgit:gittutorial[7], linkgit:gittutorial-2[7],\n-link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],\n+linkgit:giteveryday[7], linkgit:gitcvs-migration[7],\n linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],\n linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],\n linkgit:gitworkflows[7]\ndiff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\nindex d2d7c21..8475c07 100644\n--- a/Documentation/gitcore-tutorial.txt\n+++ b/Documentation/gitcore-tutorial.txt\n@@ -1667,7 +1667,7 @@ linkgit:gittutorial[7],\n linkgit:gittutorial-2[7],\n linkgit:gitcvs-migration[7],\n linkgit:git-help[1],\n-link:everyday.html[Everyday git],\n+linkgit:giteveryday[7],\n link:user-manual.html[The Git User's Manual]\n \n GIT\ndiff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt\nindex 5f4e890..b06e852 100644\n--- a/Documentation/gitcvs-migration.txt\n+++ b/Documentation/gitcvs-migration.txt\n@@ -194,7 +194,7 @@ linkgit:gittutorial[7],\n linkgit:gittutorial-2[7],\n linkgit:gitcore-tutorial[7],\n linkgit:gitglossary[7],\n-link:everyday.html[Everyday Git],\n+linkgit:giteveryday[7],\n link:user-manual.html[The Git User's Manual]\n \n GIT\ndiff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt\nnew file mode 100644\nindex 0000000..97cecce\n--- /dev/null\n+++ b/Documentation/giteveryday.txt\n@@ -0,0 +1,455 @@\n+giteveryday(7)\n+===============\n+\n+NAME\n+----\n+giteveryday - A useful minimum set of commands for Everyday Git\n+\n+SYNOPSIS\n+--------\n+\n+Everyday Git With 20 Commands Or So\n+\n+DESCRIPTION\n+-----------\n+\n+Git users can broadly be grouped into four categories for the purposes of\n+describing here a small set of useful command for everyday Git.\n+\n+*\t<<STANDALONE,Individual Developer (Standalone)>> commands are essential\n+\tfor anybody who makes a commit, even for somebody who works alone.\n+\n+*\tIf you work with other people, you will need commands listed in\n+\tthe <<PARTICIPANT,Individual Developer (Participant)>> section as well.\n+\n+*\tPeople who play the <<INTEGRATOR,Integrator>> role need to learn some\n+\tmore commands in addition to the above.\n+\n+*\t<<ADMINISTRATION,Repository Administration>> commands are for system\n+\tadministrators who are responsible for the care and feeding\n+\tof Git repositories.\n+\n+\n+Individual Developer (Standalone)[[STANDALONE]]\n+-----------------------------------------------\n+\n+A standalone individual developer does not exchange patches with\n+other people, and works alone in a single repository, using the\n+following commands.\n+\n+  * linkgit:git-init[1] to create a new repository.\n+\n+  * linkgit:git-log[1] to see what happened.\n+\n+  * linkgit:git-checkout[1] and linkgit:git-branch[1] to switch\n+    branches.\n+\n+  * linkgit:git-add[1] to manage the index file.\n+\n+  * linkgit:git-diff[1] and linkgit:git-status[1] to see what\n+    you are in the middle of doing.\n+\n+  * linkgit:git-commit[1] to advance the current branch.\n+\n+  * linkgit:git-reset[1] and linkgit:git-checkout[1] (with\n+    pathname parameters) to undo changes.\n+\n+  * linkgit:git-merge[1] to merge between local branches.\n+\n+  * linkgit:git-rebase[1] to maintain topic branches.\n+\n+  * linkgit:git-tag[1] to mark a known point.\n+\n+Examples\n+~~~~~~~~\n+\n+Use a tarball as a starting point for a new repository.::\n++\n+------------\n+$ tar zxf frotz.tar.gz\n+$ cd frotz\n+$ git init\n+$ git add . <1>\n+$ git commit -m \"import of frotz source tree.\"\n+$ git tag v2.43 <2>\n+------------\n++\n+<1> add everything under the current directory.\n+<2> make a lightweight, unannotated tag.\n+\n+Create a topic branch and develop.::\n++\n+------------\n+$ git checkout -b alsa-audio <1>\n+$ edit/compile/test\n+$ git checkout -- curses/ux_audio_oss.c <2>\n+$ git add curses/ux_audio_alsa.c <3>\n+$ edit/compile/test\n+$ git diff HEAD <4>\n+$ git commit -a -s <5>\n+$ edit/compile/test\n+$ git diff HEAD^ <6>\n+$ git commit -a --amend <7>\n+$ git checkout master <8>\n+$ git merge alsa-audio <9>\n+$ git log --since='3 days ago' <10>\n+$ git log v2.43.. curses/ <11>\n+------------\n++\n+<1> create a new topic branch.\n+<2> revert your botched changes in `curses/ux_audio_oss.c`.\n+<3> you need to tell Git if you added a new file; removal and\n+modification will be caught if you do `git commit -a` later.\n+<4> to see what changes you are committing.\n+<5> commit everything, as you have tested, with your sign-off.\n+<6> look at all your changes including the previous commit.\n+<7> amend the previous commit, adding all your new changes,\n+using your original message.\n+<8> switch to the master branch.\n+<9> merge a topic branch into your master branch.\n+<10> review commit logs; other forms to limit output can be\n+combined and include `10` (equiv. `--max-count=10`, to show 10 commits),\n+`--until=2005-12-10`, etc.\n+<11> view only the changes that touch what's in `curses/`\n+directory, since `v2.43` tag.\n+\n+\n+Individual Developer (Participant)[[PARTICIPANT]]\n+-------------------------------------------------\n+\n+A developer working as a participant in a group project needs to\n+learn how to communicate with others, and uses these commands in\n+addition to the ones needed by a standalone developer.\n+\n+  * linkgit:git-clone[1] from the upstream to prime your local\n+    repository.\n+\n+  * linkgit:git-pull[1] and linkgit:git-fetch[1] from \"origin\"\n+    to keep up-to-date with the upstream.\n+\n+  * linkgit:git-push[1] to shared repository, if you adopt CVS\n+    style shared repository workflow.\n+\n+  * linkgit:git-format-patch[1] to prepare e-mail submission, if\n+    you adopt Linux kernel-style public forum workflow.\n+\n+  * linkgit:git-send-email[1] to send your e-mail submission without\n+    corruption by your MUA.\n+\n+  * linkgit:git-request-pull[1] to create a summary of changes\n+    for your upstream to pull.\n+\n+\n+Examples\n+~~~~~~~~\n+\n+Clone the upstream and work on it.  Feed changes to upstream.::\n++\n+------------\n+$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6\n+$ cd my2.6\n+$ git checkout -b mine master <1>\n+$ edit/compile/test; git commit -a -s <2>\n+$ git format-patch master <3>\n+$ git send-email --to=\"person <email@example.com>\" 00*.patch <4>\n+$ git checkout master <5>\n+$ git pull <6>\n+$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>\n+$ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>\n+$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <9>\n+$ git reset --hard ORIG_HEAD <10>\n+$ git gc <11>\n+------------\n++\n+<1> checkout a new branch `mine` from master.\n+<2> repeat as needed.\n+<3> extract patches from your branch, relative to master,\n+<4> and email them.\n+<5> return to `master`, ready to see what's new\n+<6> `git pull` fetches from `origin` by default and merges into the\n+current branch.\n+<7> immediately after pulling, look at the changes done upstream\n+since last time we checked, only in the\n+area we are interested in.\n+<8> check the branch names in an external repository (if not known).\n+<9> fetch from a specific branch `ALL` from a specific repository\n+and merge it.\n+<10> revert the pull.\n+<11> garbage collect leftover objects from reverted pull.\n+\n+\n+Push into another repository.::\n++\n+------------\n+satellite$ git clone mothership:frotz frotz <1>\n+satellite$ cd frotz\n+satellite$ git config --get-regexp '^(remote|branch)\\.' <2>\n+remote.origin.url mothership:frotz\n+remote.origin.fetch refs/heads/*:refs/remotes/origin/*\n+branch.master.remote origin\n+branch.master.merge refs/heads/master\n+satellite$ git config remote.origin.push \\\n+           +refs/heads/*:refs/remotes/satellite/* <3>\n+satellite$ edit/compile/test/commit\n+satellite$ git push origin <4>\n+\n+mothership$ cd frotz\n+mothership$ git checkout master\n+mothership$ git merge satellite/master <5>\n+------------\n++\n+<1> mothership machine has a frotz repository under your home\n+directory; clone from it to start a repository on the satellite\n+machine.\n+<2> clone sets these configuration variables by default.\n+It arranges `git pull` to fetch and store the branches of mothership\n+machine to local `remotes/origin/*` remote-tracking branches.\n+<3> arrange `git push` to push all local branches to\n+their corresponding branch of the mothership machine.\n+<4> push will stash all our work away on `remotes/satellite/*`\n+remote-tracking branches on the mothership machine.  You could use this\n+as a back-up method. Likewise, you can pretend that mothership\n+\"fetched\" from you (useful when access is one sided).\n+<5> on mothership machine, merge the work done on the satellite\n+machine into the master branch.\n+\n+Branch off of a specific tag.::\n++\n+------------\n+$ git checkout -b private2.6.14 v2.6.14 <1>\n+$ edit/compile/test; git commit -a\n+$ git checkout master\n+$ git cherry-pick v2.6.14..private2.6.14 <2>\n+------------\n++\n+<1> create a private branch based on a well known (but somewhat behind)\n+tag.\n+<2> forward port all changes in `private2.6.14` branch to `master` branch\n+without a formal \"merging\". Or longhand +\n+`git format-patch -k -m --stdout v2.6.14..private2.6.14 |\n+  git am -3 -k`\n+\n+An alternate participant submission mechanism is using the\n+`git request-pull` or pull-request mechanisms (e.g as used on\n+GitHub (www.github.com) to notify your upstream of your\n+contribution.\n+\n+Integrator[[INTEGRATOR]]\n+------------------------\n+\n+A fairly central person acting as the integrator in a group\n+project receives changes made by others, reviews and integrates\n+them and publishes the result for others to use, using these\n+commands in addition to the ones needed by participants.\n+\n+This section can also be used by those who respond to `git\n+request-pull` or pull-request on GitHub (www.github.com) to\n+integrate the work of others into their history. An sub-area\n+lieutenant for a repository will act both as a participant and\n+as an integrator.\n+\n+\n+  * linkgit:git-am[1] to apply patches e-mailed in from your\n+    contributors.\n+\n+  * linkgit:git-pull[1] to merge from your trusted lieutenants.\n+\n+  * linkgit:git-format-patch[1] to prepare and send suggested\n+    alternative to contributors.\n+\n+  * linkgit:git-revert[1] to undo botched commits.\n+\n+  * linkgit:git-push[1] to publish the bleeding edge.\n+\n+\n+Examples\n+~~~~~~~~\n+\n+A typical integrator's Git day.::\n++\n+------------\n+$ git status <1>\n+$ git branch --no-merged master <2>\n+$ mailx <3>\n+& s 2 3 4 5 ./+to-apply\n+& s 7 8 ./+hold-linus\n+& q\n+$ git checkout -b topic/one master\n+$ git am -3 -i -s ./+to-apply <4>\n+$ compile/test\n+$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5>\n+$ git checkout topic/one && git rebase master <6>\n+$ git checkout pu && git reset --hard next <7>\n+$ git merge topic/one topic/two && git merge hold/linus <8>\n+$ git checkout maint\n+$ git cherry-pick master~4 <9>\n+$ compile/test\n+$ git tag -s -m \"GIT 0.99.9x\" v0.99.9x <10>\n+$ git fetch ko && for branch in master maint next pu <11>\n+    do\n+        git show-branch ko/$branch $branch <12>\n+    done\n+$ git push --follow-tags ko <13>\n+------------\n++\n+<1> see what you were in the middle of doing, if anything.\n+<2> see which branches haven't been merged into `master` yet.\n+Likewise for any other integration branches e.g. `maint`, `next`\n+and `pu` (potential updates).\n+<3> read mails, save ones that are applicable, and save others\n+that are not quite ready (other mail readers are available).\n+<4> apply them, interactively, with your sign-offs.\n+<5> create topic branch as needed and apply, again with sign-offs.\n+<6> rebase internal topic branch that has not been merged to the\n+master or exposed as a part of a stable branch.\n+<7> restart `pu` every time from the next.\n+<8> and bundle topic branches still cooking.\n+<9> backport a critical fix.\n+<10> create a signed tag.\n+<11> make sure master was not accidentally rewound beyond that\n+already pushed out.  `ko` shorthand points at the Git maintainer's\n+repository at kernel.org, and looks like this:\n++\n+------------\n+(in .git/config)\n+[remote \"ko\"]\n+        url = kernel.org:/pub/scm/git/git.git\n+        fetch = refs/heads/*:refs/remotes/ko/*\n+        push = refs/heads/master\n+        push = refs/heads/next\n+        push = +refs/heads/pu\n+        push = refs/heads/maint\n+------------\n++\n+<12> In the output from `git show-branch`, `master` should have\n+everything `ko/master` has, and `next` should have\n+everything `ko/next` has, etc.\n+<13> push out the bleeding edge, together with new tags that point\n+into the pushed history.\n+\n+\n+Repository Administration[[ADMINISTRATION]]\n+-------------------------------------------\n+\n+A repository administrator uses the following tools to set up\n+and maintain access to the repository by developers.\n+\n+  * linkgit:git-daemon[1] to allow anonymous download from\n+    repository.\n+\n+  * linkgit:git-shell[1] can be used as a 'restricted login shell'\n+    for shared central repository users.\n+\n+  * linkgit:git-http-backend[1] provides a server side implementation\n+    of Git-over-HTTP (\"Smart http\") allowing both fetch and push services.\n+\n+  * linkgit:gitweb[1] provides a web front-end to Git repositories,\n+    which can be set-up using the linkgit:git-instaweb[1] script.\n+\n+link:howto/update-hook-example.html[update hook howto] has a good\n+example of managing a shared central repository.\n+\n+In addition there are a number of other widely deployed hosting, browsing\n+and reviewing solutions such as:\n+\n+  * gitolite, gerrit code review, cgit and others.\n+\n+Examples\n+~~~~~~~~\n+We assume the following in /etc/services::\n++\n+------------\n+$ grep 9418 /etc/services\n+git\t\t9418/tcp\t\t# Git Version Control System\n+------------\n+\n+Run git-daemon to serve /pub/scm from inetd.::\n++\n+------------\n+$ grep git /etc/inetd.conf\n+git\tstream\ttcp\tnowait\tnobody \\\n+  /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm\n+------------\n++\n+The actual configuration line should be on one line.\n+\n+Run git-daemon to serve /pub/scm from xinetd.::\n++\n+------------\n+$ cat /etc/xinetd.d/git-daemon\n+# default: off\n+# description: The Git server offers access to Git repositories\n+service git\n+{\n+        disable = no\n+        type            = UNLISTED\n+        port            = 9418\n+        socket_type     = stream\n+        wait            = no\n+        user            = nobody\n+        server          = /usr/bin/git-daemon\n+        server_args     = --inetd --export-all --base-path=/pub/scm\n+        log_on_failure  += USERID\n+}\n+------------\n++\n+Check your xinetd(8) documentation and setup, this is from a Fedora system.\n+Others might be different.\n+\n+Give push/pull only access to developers using git-over-ssh.::\n+\n+e.g. those using:\n+`$ git push/pull ssh://host.xz/pub/scm/project`\n++\n+------------\n+$ grep git /etc/passwd <1>\n+alice:x:1000:1000::/home/alice:/usr/bin/git-shell\n+bob:x:1001:1001::/home/bob:/usr/bin/git-shell\n+cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell\n+david:x:1003:1003::/home/david:/usr/bin/git-shell\n+$ grep git /etc/shells <2>\n+/usr/bin/git-shell\n+------------\n++\n+<1> log-in shell is set to /usr/bin/git-shell, which does not\n+allow anything but `git push` and `git pull`.  The users require\n+ssh access to the machine.\n+<2> in many distributions /etc/shells needs to list what is used\n+as the login shell.\n+\n+CVS-style shared repository.::\n++\n+------------\n+$ grep git /etc/group <1>\n+git:x:9418:alice,bob,cindy,david\n+$ cd /home/devo.git\n+$ ls -l <2>\n+  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master\n+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches\n+  -rw-rw-r--   1 david git    84 Dec  4 22:40 config\n+  -rw-rw-r--   1 david git    58 Dec  4 22:40 description\n+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks\n+  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index\n+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info\n+  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects\n+  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs\n+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes\n+$ ls -l hooks/update <3>\n+  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update\n+$ cat info/allowed-users <4>\n+refs/heads/master\talice\\|cindy\n+refs/heads/doc-update\tbob\n+refs/tags/v[0-9]*\tdavid\n+------------\n++\n+<1> place the developers into the same git group.\n+<2> and make the shared repository writable by the group.\n+<3> use update-hook example by Carl from Documentation/howto/\n+for branch policy control.\n+<4> alice and cindy can push into master, only bob can push into doc-update.\n+david is the release manager and is the only person who can\n+create and push version tags.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitglossary.txt b/Documentation/gitglossary.txt\nindex e52de7d..212e254 100644\n--- a/Documentation/gitglossary.txt\n+++ b/Documentation/gitglossary.txt\n@@ -19,7 +19,7 @@ SEE ALSO\n linkgit:gittutorial[7],\n linkgit:gittutorial-2[7],\n linkgit:gitcvs-migration[7],\n-link:everyday.html[Everyday Git],\n+linkgit:giteveryday[7],\n link:user-manual.html[The Git User's Manual]\n \n GIT\ndiff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt\nindex 3109ea8..f6fbf81 100644\n--- a/Documentation/gittutorial-2.txt\n+++ b/Documentation/gittutorial-2.txt\n@@ -403,7 +403,7 @@ What next?\n \n At this point you should know everything necessary to read the man\n pages for any of the git commands; one good place to start would be\n-with the commands mentioned in link:everyday.html[Everyday Git].  You\n+with the commands mentioned in linkgit:giteveryday[7].  You\n should be able to find any unknown jargon in linkgit:gitglossary[7].\n \n The link:user-manual.html[Git User's Manual] provides a more\n@@ -427,7 +427,7 @@ linkgit:gitcvs-migration[7],\n linkgit:gitcore-tutorial[7],\n linkgit:gitglossary[7],\n linkgit:git-help[1],\n-link:everyday.html[Everyday Git],\n+linkgit:giteveryday[7],\n link:user-manual.html[The Git User's Manual]\n \n GIT\ndiff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt\nindex 8262196..af9f709 100644\n--- a/Documentation/gittutorial.txt\n+++ b/Documentation/gittutorial.txt\n@@ -656,7 +656,7 @@ digressions that may be interesting at this point are:\n   * linkgit:gitworkflows[7]: Gives an overview of recommended\n     workflows.\n \n-  * link:everyday.html[Everyday Git with 20 Commands Or So]\n+  * linkgit:giteveryday[7]: Everyday Git with 20 Commands Or So.\n \n   * linkgit:gitcvs-migration[7]: Git for CVS users.\n \n@@ -668,7 +668,7 @@ linkgit:gitcore-tutorial[7],\n linkgit:gitglossary[7],\n linkgit:git-help[1],\n linkgit:gitworkflows[7],\n-link:everyday.html[Everyday Git],\n+linkgit:giteveryday[7],\n link:user-manual.html[The Git User's Manual]\n \n GIT\ndiff --git a/README b/README\nindex 15a8e23..1083735 100644\n--- a/README\n+++ b/README\n@@ -27,7 +27,7 @@ Torvalds with help of a group of hackers around the net.\n Please read the file INSTALL for installation instructions.\n \n See Documentation/gittutorial.txt to get started, then see\n-Documentation/everyday.txt for a useful minimum set of commands, and\n+Documentation/giteveryday.txt for a useful minimum set of commands, and\n Documentation/git-commandname.txt for documentation of each command.\n If git has been correctly installed, then the tutorial can also be\n read with \"man gittutorial\" or \"git help tutorial\", and the\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 8343b40..b3c818e 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -421,6 +421,7 @@ static struct {\n \tconst char *help;\n } common_guides[] = {\n \t{ \"attributes\", N_(\"Defining attributes per path\") },\n+\t{ \"everyday\", N_(\"Everyday Git With 20 Commands Or So\") },\n \t{ \"glossary\", N_(\"A Git glossary\") },\n \t{ \"ignore\", N_(\"Specifies intentionally untracked files to ignore\") },\n \t{ \"modules\", N_(\"Defining submodule properties\") },\n-- \n1.9.4.msysgit.0\n"},{"id":"250498","messageId":"xmqqtx3b4iul.fsf@gitster.dls.corp.google.com","threadId":"37709","inReplyTo":"1412976337-2476-1-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH v4 0/3] Make 'git help everyday' work","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-10T23:15:30Z","receivedAt":"2014-10-10T23:15:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks.\n\nLooked alright from a cursory read; I tweaked s/10/-10/ where you\ngave examples of limiting output from \"git log\" before queuing.\n"},{"id":"250505","messageId":"B8CF69B23B1745B19DA8CE566B7F2FD1@PhilipOakley","threadId":"37709","inReplyTo":"xmqqtx3b4iul.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v4 0/3] Make 'git help everyday' work","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-11T10:09:24Z","receivedAt":"2014-10-11T10:09:24Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" <gitster@pobox.com>\n> Thanks.\n> \n> Looked alright from a cursory read; I tweaked s/10/-10/ where you\n> gave examples of limiting output from \"git log\" before queuing.\n\nThat was my mis-reading. I'd even noticed that it looked 'different'\nbut just didn't see the leading '-' when checking the man page.\n--\nThanks\nPhilip\n"}]}