Re: [PATCH v3 1/3] doc: modernise everyday.txt wording and format in man page style

[Junio C Hamano <gitster@pobox.com>]

Philip Oakley <philipoakley@iee.org> writes:

> @@ -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?

> @@ -131,27 +145,34 @@ Clone the upstream and work on it.  Feed changes to upstream.::
>  ------------
>  $ 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 send-email --to="person <email@example.com>" 00*.patch <4>
> +$ 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

> +$ 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.

> +<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).

> -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".


> @@ -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.

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.

Thanks.