[PATCH v4 0/3] Make 'git help everyday' work

[Philip Oakley]

This is hopefully the final revision of the patch...
and integrates Junio's comments.

I've eye-balled the man page and web page results, and corrected a few quote / back tick
items to be more consistent.

Re: [PATCH v3 1/3] doc: modernise everyday.txt wording and format in man page style
From: "Junio C Hamano" <***@pobox.com>
Sent: Tuesday, September 30, 2014 12:24 AM
Subject: Re: [PATCH v3 1/3] doc: modernise everyday.txt wording and format in man page style

@@ -45,7 +58,7 @@ following commands.
* linkgit:git-rebase[1] to maintain topic branches.
- * linkgit:git-tag[1] to mark known point.
+ * linkgit:git-tag[1] to mark a known point.

I really appreciate your attention to details here.

+<10> review commit logs; other forms to limit output can be
combined and include `--max-count=10` (show 10 commits),
`--until=2005-12-10`, etc.

s/--max-count=//; perhaps?

I've shown both in the update, as it's a help guide. How does it look?

------------
$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
$ cd my2.6
+$ git checkout -b mine master <1>
+$ edit/compile/test; git commit -a -s <2>
+$ git format-patch master <3>
+$ git pull <5>

This may be found somewhat questionable by some people, as "mine"
does not build on the master at origin. Insert "git checkout master"
before this step to cause <5> update the pristine copy of their
master, perhaps? That way, the next step

I'd misunderstood this initially (confusion as to build start point).
I've added the checkout with a comment, and renumber those following.

+$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <6>

starts making more sense.

+$ git fetch --tags <11>
...
+<11> from time to time, obtain official tags from the `origin`
and store them under `.git/refs/tags/`.

I am not sure if "fetch --tags" still needs to be taught, especially
in a "quick guide" document, because "fetch" has auto-followed
relevant tags for a long time since the original version of this
document was written.

Done - removed.

+<3> arrange `git push` to push all local branches to
+their corresponding branch of the mothership machine.
+<4> push will stash all our work away on `remotes/satellite/*`
+remote-tracking branches on the mothership machine. You could use this
as a back-up method.

The original mentions "a back-up method", but a larger benefit of
this kind of settings is that it lets you pretend that mothership
"fetched" from you.
We may want to say "You can use this to pretend as if the origin,
aka mothership, ran 'git fetch' from you, aka satellite". This is
especially true because the next step <5> is about how to integrate
your work done on 'satellite' into 'mothership' that cannot fetch
from 'satellite' (imagine satellite is behind a NAT and it can only
ssh out to mothership but not the other way around).

Text updated to include those points.

-Integrator[[Integrator]]
+Integrator[[INTEGRATOR]]
------------------------
A fairly central person acting as the integrator in a group
@@ -213,6 +235,9 @@ project receives changes made by others, reviews and integrates
them and publishes the result for others to use, using these
commands in addition to the ones needed by participants.
+This section can also be applied to a git-request-pull workflow,
+or the GitHub (www.github.com) pull-request flow.

Clarify which end of that workflow this can be applied, perhaps?
E.g. "... also be used by the person who responds to 'git
request-pull' or pull-request on GitHub to integrate others' work
into your history".

Sorted, as below.

@@ -225,23 +250,26 @@ commands in addition to the ones needed by participants.
* linkgit:git-push[1] to publish the bleeding edge.
+ * linkgit:git-request-pull[1] to create a summary of changes
+ for your upstream to pull.
+

This new item looks somewhat out of place, doesn't it? It is
because this is a participant item, not an integrator item.

The bullet item moved to Participant, and the text there updated.

Yes, I know a sub-area lieutenant would request a pull by the
top-level maintainer, but when you interact with your 'upstream',
you are not acting as an integrator.
If you really want to add request-pull to common 20-or-so commands,
it would make more sense to do so in the participant's section and
to explain that an sub-area lieutenant acts both as a participant
and as an integrator.

Added text in line with your comment.

Thanks.

--

Philip Oakley (3):
doc: modernise everyday.txt wording and format in man page style
doc: Makefile regularise OBSOLETE_HTML list building
Make 'git help everyday' work

Documentation/Makefile | 6 +-
Documentation/everyday.txt | 413 ---------------------------------
Documentation/everyday.txto | 9 +
Documentation/git-push.txt | 2 +-
Documentation/git.txt | 4 +-
Documentation/gitcore-tutorial.txt | 2 +-
Documentation/gitcvs-migration.txt | 2 +-
Documentation/giteveryday.txt | 455 +++++++++++++++++++++++++++++++++++++
Documentation/gitglossary.txt | 2 +-
Documentation/gittutorial-2.txt | 4 +-
Documentation/gittutorial.txt | 4 +-
README | 2 +-
builtin/help.c | 1 +
13 files changed, 480 insertions(+), 426 deletions(-)
delete mode 100644 Documentation/everyday.txt
create mode 100644 Documentation/everyday.txto
create mode 100644 Documentation/giteveryday.txt