[PATCH] user-manual: Rewrite git-gc section for automatic packing

[PATCH] user-manual: Rewrite git-gc section for automatic packing

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

This should have happened back in 2007, when `git gc` learned about
auto:

  commit e9831e83e063844b90cf9e525d0003715dd8b395
  Author: Junio C Hamano <gitster@pobox.com>
  Date:   Mon Sep 17 00:39:52 2007 -0700

    git-gc --auto: add documentation.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
I'd also be happy just dropping the whole git-gc section ;).

 Documentation/user-manual.txt | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5077e7c..d14e3c7 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1562,17 +1562,13 @@ Ensuring good performance
 -------------------------
 
 On large repositories, Git depends on compression to keep the history
-information from taking up too much space on disk or in memory.
+information from taking up too much space on disk or in memory.  Some
+git commands may automatically run linkgit:git-gc[1], so you don't
+have to worry about running it manually.  However, compressing large
+repositories may take some time, so you might want to disable
+automatic comression and run it explicitly when you are not doing
+other work.
 
-This compression is not performed automatically.  Therefore you
-should occasionally run linkgit:git-gc[1]:
-
--------------------------------------------------
-$ git gc
--------------------------------------------------
-
-to recompress the archive.  This can be very time-consuming, so
-you may prefer to run `git gc` when you are not doing other work.
 
 
 [[ensuring-reliability]]
-- 
1.8.1.336.g94702dd

Re: [PATCH] user-manual: Rewrite git-gc section for automatic packing

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> This should have happened back in 2007, when `git gc` learned about
> auto:
>
>   commit e9831e83e063844b90cf9e525d0003715dd8b395
>   Author: Junio C Hamano <gitster@pobox.com>
>   Date:   Mon Sep 17 00:39:52 2007 -0700
>
>     git-gc --auto: add documentation.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
> I'd also be happy just dropping the whole git-gc section ;).
>
>  Documentation/user-manual.txt | 16 ++++++----------
>  1 file changed, 6 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 5077e7c..d14e3c7 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1562,17 +1562,13 @@ Ensuring good performance
>  -------------------------
>  
>  On large repositories, Git depends on compression to keep the history
> -information from taking up too much space on disk or in memory.
> +information from taking up too much space on disk or in memory.  Some
> +git commands may automatically run linkgit:git-gc[1], so you don't
> +have to worry about running it manually.  However, compressing large
> +repositories may take some time, so you might want to disable
> +automatic comression and run it explicitly when you are not doing
> +other work.

I'd rather phrase it like "... may take long, so you would want to
run it explicitly from time to time to avoid automatic gc kicking in
when it is not convenient for you".

> -This compression is not performed automatically.  Therefore you
> -should occasionally run linkgit:git-gc[1]:
> -
> --------------------------------------------------
> -$ git gc
> --------------------------------------------------
> -
> -to recompress the archive.  This can be very time-consuming, so
> -you may prefer to run `git gc` when you are not doing other work.

Removal of this is a good change, though.

Re: [PATCH] user-manual: Rewrite git-gc section for automatic packing

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 848 bytes --]

On Fri, Feb 08, 2013 at 09:36:53AM -0800, Junio C Hamano wrote:
> I'd rather phrase it like "... may take long, so you would want to
> run it explicitly from time to time to avoid automatic gc kicking in
> when it is not convenient for you".

Works for me.

> Removal of this is a good change, though.

I just read through the manual cover to cover, so I have a number of
other fixes in the pipe (from which I've already submitted the
receive.denyCurrentBranch patch).  Should I bundle them all into a
single series to reduce clutter on the list, or will that just lead to
resending boring fixes while we hash out the right handling for more
involved ones?

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH] user-manual: Rewrite git-gc section for automatic packing

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> I just read through the manual cover to cover, so I have a number of
> other fixes in the pipe (from which I've already submitted the
> receive.denyCurrentBranch patch).

Wonderful.

> ...  Should I bundle them all into a
> single series to reduce clutter on the list,...

I do think it makes much difference between a single series that
consists of 47 separate patches and a flood of 47 unrelated patches.
As long as it is not a single patch with 200 hunks, some of which
has to be redone repeatedly, I think it is fine either way.

Many of them may be a no-brainer to accept on the first try, while
some may have to be improved with the input from the list and will
be rerolled.  I would imagine the initial round would be:

	[PATCH v1 00/47] User manual updates
         [PATCH v1 01/47] user-manual: update description of 'xyzzy'
         [PATCH v1 02/47] user-manual: update description of 'frotz'
 	 ...
         [PATCH v1 47/47] user-manual: update description of 'nitfol'

and after reviewing, some of them need to be redone in v2; the cover
letter for v2 would say something like

	[PATCH v2 00/52] User manual updates

	The patches 01-17, 19, 22-36, 39, 42-47 are the same as in
        v1; 48-52 are new.

And people who missed the v1 review cycle may have a chance to look
at and respond to [PATCH v2 06/52] which may result in an update of
that patch to address issues that reviewers of the initial round may
have missed.

Re: [PATCH] user-manual: Rewrite git-gc section for automatic packing

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> I just read through the manual cover to cover, so I have a number of
> other fixes in the pipe (from which I've already submitted the
> receive.denyCurrentBranch patch).

Wonderful.

> ...  Should I bundle them all into a
> single series to reduce clutter on the list,...

I do not think it makes much difference between a single series that
consists of 47 separate patches and a flood of 47 unrelated patches.
As long as it is not a single patch with 200 hunks, some of which
has to be redone repeatedly, I think it is fine either way.

Hopefully, many of them may be a no-brainer to accept on the first
try, while some may have to be improved with the input from the list
and will be rerolled.  I would imagine the initial round would be:

        [PATCH v1 00/47] User manual updates
         [PATCH v1 01/47] user-manual: update description of 'xyzzy'
         [PATCH v1 02/47] user-manual: update description of 'frotz'
         ...
         [PATCH v1 47/47] user-manual: update description of 'nitfol'

and after reviewing, some of them need to be redone in v2; the cover
letter for v2 would say something like

        [PATCH v2 00/52] User manual updates

        The patches 01-17, 19, 22-36, 39, 42-47 are the same as in
        v1; 48-52 are new.

And people who missed the v1 review cycle may have a chance to look
at and respond to [PATCH v2 06/52] which may result in an update of
that patch to address issues that reviewers of the initial round may
have missed.

[PATCH v2 00/15] User manual updates

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

This combines my ealier patches:

* user-manual: Rewrite git-gc section for automatic packing
* user-manual: Update for receive.denyCurrentBranch=refuse

With a number of additional fixups.  Changes since v1:

* user-manual: Rewrite git-gc section for automatic packing:
  - Reworded following suggestions from Junio.  This removed the
    phrase containing the 'comression' typo pointed out by Javier.
* user-manual: Update for receive.denyCurrentBranch=refuse
  - No changes.

Most of the patches are well-focused, with the exception of
"Standardize backtick quoting".  I can break this up into smaller
chunks (e.g. "Standardize backtick quoting in Chapter 1", "Standardize
backtick quoting in Chapter 2", …) if this is too much to bite off in
one patch.

I may add additional patches onto the end of this series as I make new
fixes and the series cooks on the list.

W. Trevor King (15):
  user-manual: Rewrite git-gc section for automatic packing
  user-manual: Update for receive.denyCurrentBranch=refuse
  user-manual: Use 'remote add' to setup push URLs
  user-manual: Use git branch --merged
  user-manual: Add a few references to 'git rebase -i'
  user-manual: Give 'git push -f' as an alternative to +master
  user-manual: Mention 'git remote add' for remote branch config
  user-manual: Standardize backtick quoting
  user-manual: Use 'git config --global user.*' for setup
  user-manual: Fix 'both: so' -> 'both; so' typo
  user-manual: Fix 'http' -> 'HTTP' typos
  user-manual: Use request-pull to generate "please pull" text
  user-manual: Fix 'you - Git' -> 'you--Git' typo
  user-manual: Flesh out uncommitted changes and submodule updates
  user-manual: Use --format=tar.gz to create a gzipped tarball

 Documentation/user-manual.txt | 436 +++++++++++++++++++++++-------------------
 1 file changed, 243 insertions(+), 193 deletions(-)

-- 
1.8.1.336.g94702dd

[PATCH v2 01/15] user-manual: Rewrite git-gc section for automatic packing

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

This should have happened back in 2007, when `git gc` learned about
auto (e9831e8, git-gc --auto: add documentation, 2007-09-17).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5077e7c..222545b 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1562,17 +1562,11 @@ Ensuring good performance
 -------------------------
 
 On large repositories, Git depends on compression to keep the history
-information from taking up too much space on disk or in memory.
-
-This compression is not performed automatically.  Therefore you
-should occasionally run linkgit:git-gc[1]:
-
--------------------------------------------------
-$ git gc
--------------------------------------------------
-
-to recompress the archive.  This can be very time-consuming, so
-you may prefer to run `git gc` when you are not doing other work.
+information from taking up too much space on disk or in memory.  Some
+git commands may automatically run linkgit:git-gc[1], so you don't
+have to worry about running it manually.  However, compressing a large
+repository may take a while, so you may want to call `gc` explicitly
+to avoid automatic compression kicking in when it is not convenient.
 
 
 [[ensuring-reliability]]
-- 
1.8.1.336.g94702dd

[PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

acd2a45 (Refuse updating the current branch in a non-bare repository
via push, 2009-02-11) changed the default to refuse such a push, but
it forgot to update the docs.

7d182f5 (Documentation: receive.denyCurrentBranch defaults to
'refuse', 2010-03-17) updated Documentation/config.txt, but forgot to
update the user manual.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 222545b..8524c08 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1988,8 +1988,10 @@ handling this case.
 Note that the target of a "push" is normally a
 <<def_bare_repository,bare>> repository.  You can also push to a
 repository that has a checked-out working tree, but the working tree
-will not be updated by the push.  This may lead to unexpected results if
-the branch you push to is the currently checked-out branch!
+will not be updated by the push.  To protect against this, pushes to
+the currently checked-out branch of a repository are denied by
+default.  See the description of the receive.denyCurrentBranch option
+in linkgit:git-config[1] for details.
 
 As with `git fetch`, you may also set up configuration options to
 save typing; so, for example, after
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> acd2a45 (Refuse updating the current branch in a non-bare repository
> via push, 2009-02-11) changed the default to refuse such a push, but
> it forgot to update the docs.
>
> 7d182f5 (Documentation: receive.denyCurrentBranch defaults to
> 'refuse', 2010-03-17) updated Documentation/config.txt, but forgot to
> update the user manual.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 222545b..8524c08 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1988,8 +1988,10 @@ handling this case.
>  Note that the target of a "push" is normally a
>  <<def_bare_repository,bare>> repository.  You can also push to a
>  repository that has a checked-out working tree, but the working tree
> -will not be updated by the push.  This may lead to unexpected results if
> -the branch you push to is the currently checked-out branch!
> +will not be updated by the push.  To protect against this, pushes to
> +the currently checked-out branch of a repository are denied by
> +default.  See the description of the receive.denyCurrentBranch option
> +in linkgit:git-config[1] for details.

Nobody else felt the same logic gap between "will not be updated"
and "to protect against this" I sensed while reading this?

I would not be surprised if some readers felt as if "then why not
update it instead of rejecting?" were a valid question, without a
bit more explanation.

	You can also push to a repository that has a working tree,
	but a push to the currently checked out branch is denied for
	two reasons:

        (1) if the push were allowed to update the working tree to
            match the pushed commit, it will overwrite and lose the
            work in progress in the working tree;

	(2) the push does _not_ update the working tree for the
	    above reason, but then if the push were allowed to
	    update the tip of the branch, the next commit made based
	    on the work done in the working tree will be based on
	    the state of the tree _before_ the push but will be
	    recorded as a descendant of the pushed commit, reverting
	    changes to the contents made by the pushed commit.
	
	If you want to handle the above two risks yourself (e.g. you
	can promise that you will never make changes to the files in
	the working tree or make commit from the working tree, and
	install a post-push hook that does "git reset --hard" to
	match the working tree state to the commit that was pushed),
	you can override this by setting receive.denyCurrentBranch.

It almost makes me wonder if it also makes sense to supersede the
denyCurrentBranch setting with a new receive.currentBranch variable
(setting it to "deny" is equivalent to setting denyCurrentBranch to
true), and make "receive.currentBranch = reset" to allow a push and
always run "git reset --hard" afterwards.

If we were to do so, I would strongly be against adding "checkout"
mode that does "git reset --keep" instead of "--hard". Those who can
accept the unconditional ovewriting with "reset --hard" are the only
ones that are safe if "push" updated the tip of the branch and the
working tree.  Updating the working tree with a "reset --keep" may
appear safe because it will catch the case where a file that needs
updating by "push" is modified, but that is an incorrect assumption.
It does not mean nobody has the contents in the editor buffer with
changes yet to be written out.  An automated update to the working
tree condition has to be allowed only to a repository with nobody
sitting at the keyboard editing files in there.

Re: [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 544 bytes --]

On Sun, Feb 10, 2013 at 01:24:47PM -0800, Junio C Hamano wrote:
> I would not be surprised if some readers felt as if "then why not
> update it instead of rejecting?" were a valid question, without a
> bit more explanation.
>
> 	You can also push to a repository that has a working tree,
>   …

Looks good to me :).  Shall I just drop this patch from v3 and leave
it to you?

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> On Sun, Feb 10, 2013 at 01:24:47PM -0800, Junio C Hamano wrote:
>> I would not be surprised if some readers felt as if "then why not
>> update it instead of rejecting?" were a valid question, without a
>> bit more explanation.
>>
>> 	You can also push to a repository that has a working tree,
>>   …
>
> Looks good to me :).  Shall I just drop this patch from v3 and leave
> it to you?

No.

Others need to object to, comment on and polish what you saw from
me, before it turns into a commit.  And you need to be credited for
identifying the problem, initiating the discussion, and collecting
responses to result in the final patch.

Re: [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> "W. Trevor King" <wking@tremily.us> writes:
>
>> On Sun, Feb 10, 2013 at 01:24:47PM -0800, Junio C Hamano wrote:
>>> I would not be surprised if some readers felt as if "then why not
>>> update it instead of rejecting?" were a valid question, without a
>>> bit more explanation.
>>>
>>> 	You can also push to a repository that has a working tree,
>>>   …
>>
>> Looks good to me :).  Shall I just drop this patch from v3 and leave
>> it to you?
>
> No.
>
> Others need to object to, comment on and polish what you saw from
> me, before it turns into a commit.  And you need to be credited for
> identifying the problem, initiating the discussion, and collecting
> responses to result in the final patch.

I did not think the detailed discussion belongs there in the first
place, so I re-read the context.  I think the only thing the reader
of the user manual needs to learn at that point of the flow is that
they can push to a non-bare but cannot push to update the currently
checked out branch by default.  So let's tone everything down and do
this instead:

-- >8 --
From: "W. Trevor King" <wking@tremily.us>
Date: Fri, 8 Feb 2013 12:04:20 -0500
Subject: [PATCH] user-manual: Update for receive.denyCurrentBranch=refuse

acd2a45 (Refuse updating the current branch in a non-bare repository
via push, 2009-02-11) changed the default to refuse such a push, but
it forgot to update the docs.

7d182f5 (Documentation: receive.denyCurrentBranch defaults to
'refuse', 2010-03-17) updated Documentation/config.txt, but forgot to
update the user manual.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/user-manual.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 85651b5..7c534dc 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1986,9 +1986,10 @@ handling this case.
 
 Note that the target of a "push" is normally a
 <<def_bare_repository,bare>> repository.  You can also push to a
-repository that has a checked-out working tree, but the working tree
-will not be updated by the push.  This may lead to unexpected results if
-the branch you push to is the currently checked-out branch!
+repository that has a checked-out working tree, but a push to update the
+currently checked-out branch is denied by default to prevent confusion.
+See the description ofthe receive.denyCurrentBranch option
+in linkgit:git-config[1] for details.
 
 As with `git fetch`, you may also set up configuration options to
 save typing; so, for example, after

Re: Re: [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 2009 bytes --]

On Thu, Feb 14, 2013 at 10:57:21AM -0800, Junio C Hamano wrote:
> So let's tone everything down and do this instead:
> 
> -- >8 --
> From: "W. Trevor King" <wking@tremily.us>
> Date: Fri, 8 Feb 2013 12:04:20 -0500
> Subject: [PATCH] user-manual: Update for receive.denyCurrentBranch=refuse
> 
> acd2a45 (Refuse updating the current branch in a non-bare repository
> via push, 2009-02-11) changed the default to refuse such a push, but
> it forgot to update the docs.
> 
> 7d182f5 (Documentation: receive.denyCurrentBranch defaults to
> 'refuse', 2010-03-17) updated Documentation/config.txt, but forgot to
> update the user manual.
> 
> Signed-off-by: W. Trevor King <wking@tremily.us>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/user-manual.txt | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 85651b5..7c534dc 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1986,9 +1986,10 @@ handling this case.
>  
>  Note that the target of a "push" is normally a
>  <<def_bare_repository,bare>> repository.  You can also push to a
> -repository that has a checked-out working tree, but the working tree
> -will not be updated by the push.  This may lead to unexpected results if
> -the branch you push to is the currently checked-out branch!
> +repository that has a checked-out working tree, but a push to update the
> +currently checked-out branch is denied by default to prevent confusion.
> +See the description ofthe receive.denyCurrentBranch option
> +in linkgit:git-config[1] for details.
>  
>  As with `git fetch`, you may also set up configuration options to
>  save typing; so, for example, after

Looks good to me.

Thanks,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v3 0/9] User manual updates

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Changes since v2 (v2 numbering):

* 01: user-manual: Rewrite git-gc section for automatic packing
  - Dropped (graduated to 'maint')
* 02: user-manual: Update for receive.denyCurrentBranch=refuse
  - Dropped (graduated to 'master')
* 03: user-manual: Use 'remote add' to setup push URLs
  - Removed 'git config' examples
  - Show .git/config changes made by 'remote add'
* 04: user-manual: Use git branch --merged
  - Dropped (not an improvement)
* 05: user-manual: Add a few references to 'git rebase -i'
  - Removed an extra blank line
  - Restructured reroll sections:
    * cherry-pick suggestions removed
    * commit --amend discussion isolated in its own section
    * format-patch restructuring moved to its own section
    * new interactive rebase section.  The contents of this section
      borrow liberally from git-rebase.txt.
* 06: user-manual: Give 'git push -f' as an alternative to +master
* 07: user-manual: Mention 'git remote add' for remote branch config
  - Simplified section to avoid 'git config'
* 08: user-manual: Standardize backtick quoting
  - Fix `{plus}` -> `+` in backticked text
* 09: user-manual: Use 'git config --global user.*' for setup
  - Remove reference to "stanza".
* 10: user-manual: Fix 'both: so' -> 'both; so' typo
  - Dropped (graduated to 'maint')
* 11: user-manual: Fix 'http' -> 'HTTP' typos
  - Dropped (graduated to 'maint')
* 12: user-manual: Use request-pull to generate "please pull" text
  - Add an explicit push before request-pull
  - Use the `mytree` remote instead of an explicit example URL
* 13: user-manual: Fix 'you - Git' -> 'you--Git' typo
  - Dropped (graduated to 'maint')
* 14: user-manual: Flesh out uncommitted changes and submodule updates
* 15: user-manual: Use --format=tar.gz to create a gzipped tarball
  - Use `-o latest.tar.gz` instead of `--format=tar.gz`.

W. Trevor King (9):
  user-manual: Use 'remote add' to setup push URLs
  user-manual: Reorganize the reroll sections, adding 'git rebase -i'
  user-manual: Give 'git push -f' as an alternative to +master
  user-manual: Mention 'git remote add' for remote branch config
  user-manual: Standardize backtick quoting
  user-manual: Use 'git config --global user.*' for setup
  user-manual: Use request-pull to generate "please pull" text
  user-manual: Flesh out uncommitted changes and submodule updates
  user-manual: Use -o latest.tar.gz to create a gzipped tarball

 Documentation/user-manual.txt | 504 ++++++++++++++++++++++--------------------
 1 file changed, 267 insertions(+), 237 deletions(-)

-- 
1.8.1.336.g94702dd

[PATCH v3 1/9] user-manual: Use 'remote add' to setup push URLs

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

There is no need to use here documents to setup this configuration.
It is easier, less confusing, and more robust to use `git remote add`
directly.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5077e7c..a060eb6 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1998,16 +1998,21 @@ will not be updated by the push.  This may lead to unexpected results if
 the branch you push to is the currently checked-out branch!
 
 As with `git fetch`, you may also set up configuration options to
-save typing; so, for example, after
+save typing; so, for example:
+
+-------------------------------------------------
+$ git remote add public-repo ssh://yourserver.com/~you/proj.git
+-------------------------------------------------
+
+adds the following to `.git/config`:
 
 -------------------------------------------------
-$ cat >>.git/config <<EOF
 [remote "public-repo"]
-	url = ssh://yourserver.com/~you/proj.git
-EOF
+	url = yourserver.com:proj.git
+	fetch = +refs/heads/*:refs/remotes/example/*
 -------------------------------------------------
 
-you should be able to perform the above push with just
+which lets you do the same push with just
 
 -------------------------------------------------
 $ git push public-repo master
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 1/9] user-manual: Use 'remote add' to setup push URLs

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> There is no need to use here documents to setup this configuration.
> It is easier, less confusing, and more robust to use `git remote add`
> directly.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---

This looks like a good 'maint' material that can be applied straight
away there in preparation for 1.8.1.4 to me; reviewers watching from
the sideline, please stop me if you see issues.

>  Documentation/user-manual.txt | 15 ++++++++++-----
>  1 file changed, 10 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 5077e7c..a060eb6 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1998,16 +1998,21 @@ will not be updated by the push.  This may lead to unexpected results if
>  the branch you push to is the currently checked-out branch!
>  
>  As with `git fetch`, you may also set up configuration options to
> -save typing; so, for example, after
> +save typing; so, for example:
> +
> +-------------------------------------------------
> +$ git remote add public-repo ssh://yourserver.com/~you/proj.git
> +-------------------------------------------------
> +
> +adds the following to `.git/config`:
>  
>  -------------------------------------------------
> -$ cat >>.git/config <<EOF
>  [remote "public-repo"]
> -	url = ssh://yourserver.com/~you/proj.git
> -EOF
> +	url = yourserver.com:proj.git
> +	fetch = +refs/heads/*:refs/remotes/example/*
>  -------------------------------------------------
>  
> -you should be able to perform the above push with just
> +which lets you do the same push with just

As the additional "remote.public-repo.fetch" line hints, this does
more than "lets you do the same push with just [lazily]"; it also
starts pretending to have run a fetch from there immediately after
you pushed and update the remote tracking branches.  I couldn't
decide if it is a good idea to point it out in this point of the
flow as well, or it is too much detail that is not exactly relevant
while teaching "git push".  I tend to think it would be the latter.

Re: [PATCH v3 1/9] user-manual: Use 'remote add' to setup push URLs

[Jonathan Nieder]

Junio C Hamano wrote:
> "W. Trevor King" <wking@tremily.us> writes:

>> There is no need to use here documents to setup this configuration.
>> It is easier, less confusing, and more robust to use `git remote add`
>> directly.
[...]
> This looks like a good 'maint' material that can be applied straight
> away there in preparation for 1.8.1.4 to me; reviewers watching from
> the sideline, please stop me if you see issues.

Agreed --- this looks good.

[...]
> As the additional "remote.public-repo.fetch" line hints, this does
> more than "lets you do the same push with just [lazily]"; it also
> starts pretending to have run a fetch from there immediately after
> you pushed and update the remote tracking branches.  I couldn't
> decide if it is a good idea to point it out in this point of the
> flow as well, or it is too much detail that is not exactly relevant
> while teaching "git push".  I tend to think it would be the latter.

I think it's possible to improve the text here to hint that there's
more to learn (maybe a forward-reference to a section about the
remotes/* hierarchy) without getting lost in the details.  But that
problem was already there, and I don't think it should block this
improvement.

Thanks.
Jonathan

[PATCH v3 2/9] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I think this interface is often more convenient than extended cherry
picking or using 'git format-patch'.  In fact, I removed the
cherry-pick section entirely.  The entry-level suggestions for
rerolling are now:

1. git commit --amend
2. git format-patch origin
   git reset --hard origin
   ...edit and reorder patches...
   git am *.patch
3. git rebase -i origin

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 110 ++++++++++++++++++++++++------------------
 1 file changed, 63 insertions(+), 47 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a060eb6..dbffd0a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2538,6 +2538,12 @@ return mywork to the state it had before you started the rebase:
 $ git rebase --abort
 -------------------------------------------------
 
+If you need to reorder or edit a number of commits in a branch, it may
+be easier to use `git rebase -i`, which allows you to reorder and
+squash commits, as well as marking them for individual editing during
+the rebase.  See <<interactive-rebase>> for details, and
+<<reordering-patch-series>> for alternatives.
+
 [[rewriting-one-commit]]
 Rewriting a single commit
 -------------------------
@@ -2552,71 +2558,81 @@ $ git commit --amend
 which will replace the old commit by a new commit incorporating your
 changes, giving you a chance to edit the old commit message first.
 
-You can also use a combination of this and linkgit:git-rebase[1] to
-replace a commit further back in your history and recreate the
-intervening changes on top of it.  First, tag the problematic commit
-with
-
--------------------------------------------------
-$ git tag bad mywork~5
--------------------------------------------------
-
-(Either gitk or `git log` may be useful for finding the commit.)
+[[reordering-patch-series]]
+Reordering or selecting from a patch series
+-------------------------------------------
 
-Then check out that commit, edit it, and rebase the rest of the series
-on top of it (note that we could check out the commit on a temporary
-branch, but instead we're using a <<detached-head,detached head>>):
+Sometimes you want to edit a commit deeper in your history.  One
+approach is to use `git format-patch` to create a series of patches,
+then reset the state to before the patches:
 
 -------------------------------------------------
-$ git checkout bad
-$ # make changes here and update the index
-$ git commit --amend
-$ git rebase --onto HEAD bad mywork
+$ git format-patch origin
+$ git reset --hard origin
 -------------------------------------------------
 
-When you're done, you'll be left with mywork checked out, with the top
-patches on mywork reapplied on top of your modified commit.  You can
-then clean up with
+Then modify, reorder, or eliminate patches as preferred before applying
+them again with linkgit:git-am[1]:
 
 -------------------------------------------------
-$ git tag -d bad
+$ git am *.patch
 -------------------------------------------------
 
-Note that the immutable nature of Git history means that you haven't really
-"modified" existing commits; instead, you have replaced the old commits with
-new commits having new object names.
+[[interactive-rebase]]
+Using interactive rebases
+-------------------------
 
-[[reordering-patch-series]]
-Reordering or selecting from a patch series
--------------------------------------------
+You can also edit a patch series with an interactive rebase.  This is
+the same as <<reordering-patch-series,reordering a patch series using
+`format-patch`>>, so use whichever interface you like best.
 
-Given one existing commit, the linkgit:git-cherry-pick[1] command
-allows you to apply the change introduced by that commit and create a
-new commit that records it.  So, for example, if "mywork" points to a
-series of patches on top of "origin", you might do something like:
+Rebase your current HEAD on the last commit you want to retain as-is.
+For example, if you want to reorder the last 5 commits, use:
 
 -------------------------------------------------
-$ git checkout -b mywork-new origin
-$ gitk origin..mywork &
+$ git rebase -i HEAD~5
 -------------------------------------------------
 
-and browse through the list of patches in the mywork branch using gitk,
-applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using `git commit --amend`.
-The linkgit:git-gui[1] command may also help as it allows you to
-individually select diff hunks for inclusion in the index (by
-right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
-
-Another technique is to use `git format-patch` to create a series of
-patches, then reset the state to before the patches:
+This will open your editor with a list of the commits you're rebasing
 
 -------------------------------------------------
-$ git format-patch origin
-$ git reset --hard origin
--------------------------------------------------
+pick deadbee The oneline of this commit
+pick fa1afe1 The oneline of the next commit
+...
 
-Then modify, reorder, or eliminate patches as preferred before applying
-them again with linkgit:git-am[1].
+# Rebase c0ffeee..deadbee onto c0ffeee
+#
+# Commands:
+#  p, pick = use commit
+#  r, reword = use commit, but edit the commit message
+#  e, edit = use commit, but stop for amending
+#  s, squash = use commit, but meld into previous commit
+#  f, fixup = like "squash", but discard this commit's log message
+#  x, exec = run command (the rest of the line) using shell
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+# Note that empty commits are commented out
+-------------------------------------------------
+
+As explained in the comments, you can reorder commits, squash them
+together, edit commit messages, etc. by editing the list.  Once you
+are satisfied, save the list and close your editor, and the rebase
+will begin.
+
+The rebase will stop when `pick` has been replaced with `edit` or when
+a command fails due to merge errors. When you are done editing and/or
+resolving conflicts you can continue with `git rebase --continue`.  If
+you decide that things are getting too hairy, you can always bail out
+with `git rebase --abort`.  Even after the rebase is complete, you can
+still recover the original branch by using the <<reflogs,reflog>>.
+
+For a more detailed discussion of the procedure and additional tips,
+see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
 
 [[patch-series-tools]]
 Other tools
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 2/9] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> I think this interface is often more convenient than extended cherry
> picking or using 'git format-patch'.  In fact, I removed the
> cherry-pick section entirely.  The entry-level suggestions for
> rerolling are now:
>
> 1. git commit --amend
> 2. git format-patch origin
>    git reset --hard origin
>    ...edit and reorder patches...
>    git am *.patch
> 3. git rebase -i origin
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 110 ++++++++++++++++++++++++------------------
>  1 file changed, 63 insertions(+), 47 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a060eb6..dbffd0a 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2538,6 +2538,12 @@ return mywork to the state it had before you started the rebase:
>  $ git rebase --abort
>  -------------------------------------------------
>  
> +If you need to reorder or edit a number of commits in a branch, it may
> +be easier to use `git rebase -i`, which allows you to reorder and
> +squash commits, as well as marking them for individual editing during
> +the rebase.  See <<interactive-rebase>> for details, and
> +<<reordering-patch-series>> for alternatives.
> +
>  [[rewriting-one-commit]]
>  Rewriting a single commit
>  -------------------------
> @@ -2552,71 +2558,81 @@ $ git commit --amend
>  which will replace the old commit by a new commit incorporating your
>  changes, giving you a chance to edit the old commit message first.
>  

... A lot of lines removed here ...

> +[[reordering-patch-series]]

This change makes the [[rewriting-one-commit]] section say "We
already saw you can do 'commit --amend'" and nothing else.  It makes
me wonder if the remaining section is worth keeping if we go this
route.


> +[[reordering-patch-series]]
> +Reordering or selecting from a patch series
> +-------------------------------------------
>  
> +Sometimes you want to edit a commit deeper in your history.  One
> +approach is to use `git format-patch` to create a series of patches,
> +then reset the state to before the patches:
>  
>  -------------------------------------------------
> +$ git format-patch origin
> +$ git reset --hard origin
>  -------------------------------------------------
>  
> +Then modify, reorder, or eliminate patches as preferred before applying
> +them again with linkgit:git-am[1]:
>  
>  -------------------------------------------------
> +$ git am *.patch
>  -------------------------------------------------

It may be just me, but s/preferred/needed/, perhaps?

> +This will open your editor with a list of the commits you're rebasing
>  
>  -------------------------------------------------
> +pick deadbee The oneline of this commit
> +pick fa1afe1 The oneline of the next commit
> +...
>  
> +# Rebase c0ffeee..deadbee onto c0ffeee
> +#
> +# Commands:
> ...
> +# Note that empty commits are commented out
> +-------------------------------------------------
> +
> +As explained in the comments, you can reorder commits, squash them
> +together, edit commit messages, etc. by editing the list.  Once you
> +are satisfied, save the list and close your editor, and the rebase
> +will begin.
> +
> +The rebase will stop when `pick` has been replaced with `edit` or when
> +a command fails due to merge errors. When you are done editing and/or
> +resolving conflicts...

I am afraid that "due to merge errors" and "resolving conflicts" do
not look corresponding to each other for a new reader.  Also here we
say "when a command fails", but the explanation before this part
never says "list of commands".  Besides, "command" itself is not a
very good word to use as "pick" is not really a "command" (we do not
have "git pick" or "git squash"---that is why I almost always call
this "insn sheet" myself, by the way).

A way to reword the above to reduce possible confusion may be to
start with:

	This will open your editor with a list of steps to be taken
        to perform your rebase.

and then say

	... with `edit` or when a step in the list fails to
	mechanically resolve conflicts and needs your help.  When
	you are done editing ...

or something.

Re: [PATCH v3 2/9] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1911 bytes --]

On Sun, Feb 17, 2013 at 06:23:11PM -0800, Junio C Hamano wrote:
> "W. Trevor King" <wking@tremily.us> writes:
> >  [[rewriting-one-commit]]
> >  Rewriting a single commit
> >  -------------------------
> > @@ -2552,71 +2558,81 @@ $ git commit --amend
> >  which will replace the old commit by a new commit incorporating your
> >  changes, giving you a chance to edit the old commit message first.
> >  
> 
> ... A lot of lines removed here ...
> 
> > +[[reordering-patch-series]]
> 
> This change makes the [[rewriting-one-commit]] section say "We
> already saw you can do 'commit --amend'" and nothing else.  It makes
> me wonder if the remaining section is worth keeping if we go this
> route.

I think there should be some mention of `commit --amend` in the
rewriting history section.  It's a pretty straightforward idea though,
so there's not all that much to say about it ;).

> > +Then modify, reorder, or eliminate patches as preferred before applying
> > +them again with linkgit:git-am[1]:
> >  
> >  -------------------------------------------------
> > +$ git am *.patch
> >  -------------------------------------------------
> 
> It may be just me, but s/preferred/needed/, perhaps?

Sure.  I was just shifting the existing text.  Will fix in v4.

> > +The rebase will stop when `pick` has been replaced with `edit` or when
> > +a command fails due to merge errors. When you are done editing and/or
> > +resolving conflicts...
> 
> I am afraid that "due to merge errors" and "resolving conflicts" do
> not look corresponding to each other for a new reader.  Also here we
> say "when a command fails", but the explanation before this part
> never says "list of commands".

Oops.  s/command/commit/.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v3 2/9] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> On Sun, Feb 17, 2013 at 06:23:11PM -0800, Junio C Hamano wrote:
>> "W. Trevor King" <wking@tremily.us> writes:
>> >  [[rewriting-one-commit]]
>> >  Rewriting a single commit
>> >  -------------------------
>> > @@ -2552,71 +2558,81 @@ $ git commit --amend
>> >  which will replace the old commit by a new commit incorporating your
>> >  changes, giving you a chance to edit the old commit message first.
>> >  
>> 
>> ... A lot of lines removed here ...
>> 
>> > +[[reordering-patch-series]]
>> 
>> This change makes the [[rewriting-one-commit]] section say "We
>> already saw you can do 'commit --amend'" and nothing else.  It makes
>> me wonder if the remaining section is worth keeping if we go this
>> route.
>
> I think there should be some mention of `commit --amend` in the
> rewriting history section.  It's a pretty straightforward idea though,
> so there's not all that much to say about it ;).

I do think teaching "commit --amend", "rebase" and "rebase -i"
together makes sense. It just felt that the remaining piece on
"commit --amend" looked too thin in the substance, but it may be a
good change in the existing flow of text.

[PATCH v3 3/9] user-manual: Give 'git push -f' as an alternative to +master

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

This mirrors existing language in the description of 'git fetch'.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index dbffd0a..ba06b7e 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2051,6 +2051,13 @@ branch name with a plus sign:
 $ git push ssh://yourserver.com/~you/proj.git +master
 -------------------------------------------------
 
+Note the addition of the `+` sign.  Alternatively, you can use the
+`-f` flag to force the remote update, as in:
+
+-------------------------------------------------
+$ git push -f ssh://yourserver.com/~you/proj.git master
+-------------------------------------------------
+
 Normally whenever a branch head in a public repository is modified, it
 is modified to point to a descendant of the commit that it pointed to
 before.  By forcing a push in this situation, you break that convention.
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 3/9] user-manual: Give 'git push -f' as an alternative to +master

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> This mirrors existing language in the description of 'git fetch'.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---

This looks like a good 'maint' material that can be applied straight
away there in preparation for 1.8.1.4 to me; reviewers watching from
the sideline, please stop me if you see issues.

>  Documentation/user-manual.txt | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index dbffd0a..ba06b7e 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2051,6 +2051,13 @@ branch name with a plus sign:
>  $ git push ssh://yourserver.com/~you/proj.git +master
>  -------------------------------------------------
>  
> +Note the addition of the `+` sign.  Alternatively, you can use the
> +`-f` flag to force the remote update, as in:
> +
> +-------------------------------------------------
> +$ git push -f ssh://yourserver.com/~you/proj.git master
> +-------------------------------------------------
> +
>  Normally whenever a branch head in a public repository is modified, it
>  is modified to point to a descendant of the commit that it pointed to
>  before.  By forcing a push in this situation, you break that convention.

[PATCH v3 4/9] user-manual: Mention 'git remote add' for remote branch config

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I hardly ever setup remote.<name>.url using 'git config'.  While it
may be instructive to do so, we should also point out 'git remote
add'.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 40 +++++++++++++---------------------------
 1 file changed, 13 insertions(+), 27 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ba06b7e..91f1822 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2878,48 +2878,34 @@ branch.master.merge=refs/heads/master
 
 If there are other repositories that you also use frequently, you can
 create similar configuration options to save typing; for example,
-after
 
 -------------------------------------------------
-$ git config remote.example.url git://example.com/proj.git
+$ git remote add example git://example.com/proj.git
 -------------------------------------------------
 
-then the following two commands will do the same thing:
+adds the following to `.git/config`:
 
 -------------------------------------------------
-$ git fetch git://example.com/proj.git master:refs/remotes/example/master
-$ git fetch example master:refs/remotes/example/master
+[remote "example"]
+	url = git://example.com/proj.git
+	fetch = +refs/heads/*:refs/remotes/example/*
 -------------------------------------------------
 
-Even better, if you add one more option:
-
--------------------------------------------------
-$ git config remote.example.fetch master:refs/remotes/example/master
--------------------------------------------------
+Also note that the above configuration can be performed by directly
+editing the file `.git/config` instead of using linkgit:git-remote[1].
 
-then the following commands will all do the same thing:
+After configuring the remote, the following two commands will do the
+same thing:
 
 -------------------------------------------------
-$ git fetch git://example.com/proj.git master:refs/remotes/example/master
-$ git fetch example master:refs/remotes/example/master
+$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
+$ git fetch example +refs/heads/*:refs/remotes/example/*
 $ git fetch example
 -------------------------------------------------
 
-You can also add a "+" to force the update each time:
-
--------------------------------------------------
-$ git config remote.example.fetch +master:refs/remotes/example/master
--------------------------------------------------
-
-Don't do this unless you're sure you won't mind "git fetch" possibly
-throwing away commits on 'example/master'.
-
-Also note that all of the above configuration can be performed by
-directly editing the file .git/config instead of using
-linkgit:git-config[1].
-
 See linkgit:git-config[1] for more details on the configuration
-options mentioned above.
+options mentioned above and linkgit:git-fetch[1] for more details on
+the refspec syntax.
 
 
 [[git-concepts]]
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 4/9] user-manual: Mention 'git remote add' for remote branch config

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> I hardly ever setup remote.<name>.url using 'git config'.  While it
> may be instructive to do so, we should also point out 'git remote
> add'.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---

This looks like a good 'maint' material that can be applied straight
away there in preparation for 1.8.1.4 to me (modulo one nit);
reviewers watching from the sideline, please stop me if you see
issues.

> +After configuring the remote, the following two commands will do the
> +same thing:
>  
>  -------------------------------------------------
> +$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
> +$ git fetch example +refs/heads/*:refs/remotes/example/*
>  $ git fetch example
>  -------------------------------------------------

These _three_ commands will do the same.

Re: Re: [PATCH v3 4/9] user-manual: Mention 'git remote add' for remote branch config

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 695 bytes --]

On Sun, Feb 17, 2013 at 06:26:25PM -0800, Junio C Hamano wrote:
> "W. Trevor King" <wking@tremily.us> writes:
> >  -------------------------------------------------
> > +$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
> > +$ git fetch example +refs/heads/*:refs/remotes/example/*
> >  $ git fetch example
> >  -------------------------------------------------
> 
> These _three_ commands will do the same.

Oops.  Feel free to fix this for me, and consider the revised version
signed off by me ;).

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v3 5/9] user-manual: Standardize backtick quoting

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I tried to always use backticks for:
* Paths and filenames (e.g. `.git/config`)
* Compound refs (e.g. `origin/HEAD`)
* Git commands (e.g. `git log`)
* Command arguments (e.g. `--pretty`)
* URLs (e.g. `git://`), as a subset of command arguments
* Special characters (e.g. `+` in diffs).
* Config options (e.g. `branch.<name>.remote`)

Branch and tag names are sometimes set off with double quotes,
sometimes set off with backticks, and sometimes left bare.  I tried to
judge when the intention was introducing new terms or conventions
(double quotes), to reference a recently used command argument
(backticks), or to reference the abstract branch/commit (left bare).
Obviously these are not particularly crisp definitions, so my
decisions are fairly arbitrary ;).  When a reference had already been
introduced, I changed further double-quoted instances to backticked
instances.

When new backticks increased the length of a line beyond others in
that block, I re-wrapped blocks to 72 columns.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 288 +++++++++++++++++++++---------------------
 1 file changed, 145 insertions(+), 143 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 91f1822..a79b3e31 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -19,7 +19,7 @@ Further chapters cover more specialized topics.
 
 Comprehensive reference documentation is available through the man
 pages, or linkgit:git-help[1] command.  For example, for the command
-"git clone <repo>", you can either use:
+`git clone <repo>`, you can either use:
 
 ------------------------------------------------
 $ man git-clone
@@ -66,11 +66,11 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
 The initial clone may be time-consuming for a large project, but you
 will only need to clone once.
 
-The clone command creates a new directory named after the project ("git"
-or "linux-2.6" in the examples above).  After you cd into this
+The clone command creates a new directory named after the project (`git`
+or `linux-2.6` in the examples above).  After you cd into this
 directory, you will see that it contains a copy of the project files,
 called the <<def_working_tree,working tree>>, together with a special
-top-level directory named ".git", which contains all the information
+top-level directory named `.git`, which contains all the information
 about the history of the project.
 
 [[how-to-check-out]]
@@ -188,7 +188,7 @@ As you can see, a commit shows who made the latest change, what they
 did, and why.
 
 Every commit has a 40-hexdigit id, sometimes called the "object name" or the
-"SHA-1 id", shown on the first line of the "git show" output.  You can usually
+"SHA-1 id", shown on the first line of the `git show` output.  You can usually
 refer to a commit by a shorter name, such as a tag or a branch name, but this
 longer name can also be useful.  Most importantly, it is a globally unique
 name for this commit: so if you tell somebody else the object name (for
@@ -268,35 +268,35 @@ Manipulating branches
 Creating, deleting, and modifying branches is quick and easy; here's
 a summary of the commands:
 
-git branch::
+`git branch`::
 	list all branches
-git branch <branch>::
-	create a new branch named <branch>, referencing the same
+`git branch <branch>`::
+	create a new branch named `<branch>`, referencing the same
 	point in history as the current branch
-git branch <branch> <start-point>::
-	create a new branch named <branch>, referencing
-	<start-point>, which may be specified any way you like,
+`git branch <branch> <start-point>`::
+	create a new branch named `<branch>`, referencing
+	`<start-point>`, which may be specified any way you like,
 	including using a branch name or a tag name
-git branch -d <branch>::
-	delete the branch <branch>; if the branch you are deleting
+`git branch -d <branch>`::
+	delete the branch `<branch>`; if the branch you are deleting
 	points to a commit which is not reachable from the current
 	branch, this command will fail with a warning.
-git branch -D <branch>::
+`git branch -D <branch>`::
 	even if the branch points to a commit not reachable
 	from the current branch, you may know that that commit
 	is still reachable from some other branch or tag.  In that
 	case it is safe to use this command to force Git to delete
 	the branch.
-git checkout <branch>::
-	make the current branch <branch>, updating the working
-	directory to reflect the version referenced by <branch>
-git checkout -b <new> <start-point>::
-	create a new branch <new> referencing <start-point>, and
+`git checkout <branch>`::
+	make the current branch `<branch>`, updating the working
+	directory to reflect the version referenced by `<branch>`
+`git checkout -b <new> <start-point>`::
+	create a new branch `<new>` referencing `<start-point>`, and
 	check it out.
 
 The special symbol "HEAD" can always be used to refer to the current
-branch.  In fact, Git uses a file named "HEAD" in the .git directory to
-remember which branch is current:
+branch.  In fact, Git uses a file named `HEAD` in the `.git` directory
+to remember which branch is current:
 
 ------------------------------------------------
 $ cat .git/HEAD
@@ -346,7 +346,7 @@ of the HEAD in the repository that you cloned from.  That repository
 may also have had other branches, though, and your local repository
 keeps branches which track each of those remote branches, called
 remote-tracking branches, which you
-can view using the "-r" option to linkgit:git-branch[1]:
+can view using the `-r` option to linkgit:git-branch[1]:
 
 ------------------------------------------------
 $ git branch -r
@@ -364,7 +364,7 @@ In this example, "origin" is called a remote repository, or "remote"
 for short. The branches of this repository are called "remote
 branches" from our point of view. The remote-tracking branches listed
 above were created based on the remote branches at clone time and will
-be updated by "git fetch" (hence "git pull") and "git push". See
+be updated by `git fetch` (hence `git pull`) and `git push`. See
 <<Updating-a-repository-With-git-fetch>> for details.
 
 You might want to build on one of these remote-tracking branches
@@ -374,7 +374,7 @@ on a branch of your own, just as you would for a tag:
 $ git checkout -b my-todo-copy origin/todo
 ------------------------------------------------
 
-You can also check out "origin/todo" directly to examine it or
+You can also check out `origin/todo` directly to examine it or
 write a one-off patch.  See <<detached-head,detached head>>.
 
 Note that the name "origin" is just the name that Git uses by default
@@ -386,17 +386,17 @@ Naming branches, tags, and other references
 
 Branches, remote-tracking branches, and tags are all references to
 commits.  All references are named with a slash-separated path name
-starting with "refs"; the names we've been using so far are actually
+starting with `refs`; the names we've been using so far are actually
 shorthand:
 
-	- The branch "test" is short for "refs/heads/test".
-	- The tag "v2.6.18" is short for "refs/tags/v2.6.18".
-	- "origin/master" is short for "refs/remotes/origin/master".
+	- The branch `test` is short for `refs/heads/test`.
+	- The tag `v2.6.18` is short for `refs/tags/v2.6.18`.
+	- `origin/master` is short for `refs/remotes/origin/master`.
 
 The full name is occasionally useful if, for example, there ever
 exists a tag and a branch with the same name.
 
-(Newly created refs are actually stored in the .git/refs directory,
+(Newly created refs are actually stored in the `.git/refs` directory,
 under the path given by their name.  However, for efficiency reasons
 they may also be packed together in a single file; see
 linkgit:git-pack-refs[1]).
@@ -418,7 +418,7 @@ Eventually the developer cloned from will do additional work in her
 repository, creating new commits and advancing the branches to point
 at the new commits.
 
-The command "git fetch", with no arguments, will update all of the
+The command `git fetch`, with no arguments, will update all of the
 remote-tracking branches to the latest version found in her
 repository.  It will not touch any of your own branches--not even the
 "master" branch that was created for you on clone.
@@ -438,7 +438,7 @@ $ git fetch linux-nfs
 -------------------------------------------------
 
 New remote-tracking branches will be stored under the shorthand name
-that you gave "git remote add", in this case linux-nfs:
+that you gave `git remote add`, in this case `linux-nfs`:
 
 -------------------------------------------------
 $ git branch -r
@@ -446,10 +446,10 @@ linux-nfs/master
 origin/master
 -------------------------------------------------
 
-If you run "git fetch <remote>" later, the remote-tracking branches for the
-named <remote> will be updated.
+If you run `git fetch <remote>` later, the remote-tracking branches
+for the named `<remote>` will be updated.
 
-If you examine the file .git/config, you will see that Git has added
+If you examine the file `.git/config`, you will see that Git has added
 a new stanza:
 
 -------------------------------------------------
@@ -462,7 +462,7 @@ $ cat .git/config
 -------------------------------------------------
 
 This is what causes Git to track the remote's branches; you may modify
-or delete these configuration options by editing .git/config with a
+or delete these configuration options by editing `.git/config` with a
 text editor.  (See the "CONFIGURATION FILE" section of
 linkgit:git-config[1] for details.)
 
@@ -499,7 +499,7 @@ Bisecting: 3537 revisions left to test after this
 [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
 -------------------------------------------------
 
-If you run "git branch" at this point, you'll see that Git has
+If you run `git branch` at this point, you'll see that Git has
 temporarily moved you in "(no branch)". HEAD is now detached from any
 branch and points directly to a commit (with commit id 65934...) that
 is reachable from "master" but not from v2.6.18. Compile and test it,
@@ -545,11 +545,11 @@ id, and check it out with:
 $ git reset --hard fb47ddb2db...
 -------------------------------------------------
 
-then test, run "bisect good" or "bisect bad" as appropriate, and
+then test, run `bisect good` or `bisect bad` as appropriate, and
 continue.
 
-Instead of "git bisect visualize" and then "git reset --hard
-fb47ddb2db...", you might just want to tell Git that you want to skip
+Instead of `git bisect visualize` and then `git reset --hard
+fb47ddb2db...`, you might just want to tell Git that you want to skip
 the current commit:
 
 -------------------------------------------------
@@ -561,8 +561,8 @@ bad one between some first skipped commits and a later bad commit.
 
 There are also ways to automate the bisecting process if you have a
 test script that can tell a good from a bad commit. See
-linkgit:git-bisect[1] for more information about this and other "git
-bisect" features.
+linkgit:git-bisect[1] for more information about this and other `git
+bisect` features.
 
 [[naming-commits]]
 Naming commits
@@ -591,7 +591,7 @@ $ git show HEAD~4   # the great-great-grandparent
 -------------------------------------------------
 
 Recall that merge commits may have more than one parent; by default,
-^ and ~ follow the first parent listed in the commit, but you can
+`^` and `~` follow the first parent listed in the commit, but you can
 also choose:
 
 -------------------------------------------------
@@ -640,7 +640,7 @@ running
 $ git tag stable-1 1b2e1d63ff
 -------------------------------------------------
 
-You can use stable-1 to refer to the commit 1b2e1d63ff.
+You can use `stable-1` to refer to the commit 1b2e1d63ff.
 
 This creates a "lightweight" tag.  If you would also like to include a
 comment with the tag, and possibly sign it cryptographically, then you
@@ -669,7 +669,7 @@ $ git log -S'foo()'	# commits which add or remove any file data
 -------------------------------------------------
 
 And of course you can combine all of these; the following finds
-commits since v2.5 which touch the Makefile or any file under fs:
+commits since v2.5 which touch the `Makefile` or any file under `fs`:
 
 -------------------------------------------------
 $ git log v2.5.. Makefile fs/
@@ -681,7 +681,7 @@ You can also ask git log to show patches:
 $ git log -p
 -------------------------------------------------
 
-See the "--pretty" option in the linkgit:git-log[1] man page for more
+See the `--pretty` option in the linkgit:git-log[1] man page for more
 display options.
 
 Note that git log starts with the most recent commit and works
@@ -742,8 +742,8 @@ Examples
 Counting the number of commits on a branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Suppose you want to know how many commits you've made on "mybranch"
-since it diverged from "origin":
+Suppose you want to know how many commits you've made on `mybranch`
+since it diverged from `origin`:
 
 -------------------------------------------------
 $ git log --pretty=oneline origin..mybranch | wc -l
@@ -780,7 +780,7 @@ $ git rev-list master
 e05db0fd4f31dde7005f075a84f96b360d05984b
 -------------------------------------------------
 
-Or you could recall that the ... operator selects all commits
+Or you could recall that the `...` operator selects all commits
 contained reachable from either one reference or the other but not
 both: so
 
@@ -880,7 +880,7 @@ Showing commits unique to a given branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Suppose you would like to see all the commits reachable from the branch
-head named "master" but not from any other head in your repository.
+head named `master` but not from any other head in your repository.
 
 We can list all the heads in this repository with
 linkgit:git-show-ref[1]:
@@ -894,7 +894,7 @@ a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
 -------------------------------------------------
 
-We can get just the branch-head names, and remove "master", with
+We can get just the branch-head names, and remove `master`, with
 the help of the standard utilities cut and grep:
 
 -------------------------------------------------
@@ -935,7 +935,7 @@ $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
 -------------------------------------------------
 
 will use HEAD to produce a tar archive in which each filename is
-preceded by "project/".
+preceded by `project/`.
 
 If you're releasing a new version of a software project, you may want
 to simultaneously make a changelog to include in the release
@@ -993,7 +993,7 @@ Telling Git your name
 
 Before creating any commits, you should introduce yourself to Git.  The
 easiest way to do so is to make sure the following lines appear in a
-file named .gitconfig in your home directory:
+file named `.gitconfig` in your home directory:
 
 ------------------------------------------------
 [user]
@@ -1045,7 +1045,7 @@ at step 3, Git maintains a snapshot of the tree's contents in a
 special staging area called "the index."
 
 At the beginning, the content of the index will be identical to
-that of the HEAD.  The command "git diff --cached", which shows
+that of the HEAD.  The command `git diff --cached`, which shows
 the difference between the HEAD and the index, should therefore
 produce no output at that point.
 
@@ -1084,7 +1084,7 @@ $ git diff
 
 shows the difference between the working tree and the index file.
 
-Note that "git add" always adds just the current contents of a file
+Note that `git add` always adds just the current contents of a file
 to the index; further changes to the same file will be ignored unless
 you run `git add` on the file again.
 
@@ -1155,8 +1155,9 @@ annoying to have these untracked files lying around; e.g. they make
 `git add .` practically useless, and they keep showing up in the output of
 `git status`.
 
-You can tell Git to ignore certain files by creating a file called .gitignore
-in the top level of your working directory, with contents such as:
+You can tell Git to ignore certain files by creating a file called
+`.gitignore` in the top level of your working directory, with contents
+such as:
 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.
@@ -1180,10 +1181,10 @@ for other users who clone your repository.
 
 If you wish the exclude patterns to affect only certain repositories
 (instead of every repository for a given project), you may instead put
-them in a file in your repository named .git/info/exclude, or in any file
-specified by the `core.excludesfile` configuration variable.  Some Git
-commands can also take exclude patterns directly on the command line.
-See linkgit:gitignore[5] for the details.
+them in a file in your repository named `.git/info/exclude`, or in any
+file specified by the `core.excludesfile` configuration variable.
+Some Git commands can also take exclude patterns directly on the
+command line.  See linkgit:gitignore[5] for the details.
 
 [[how-to-merge]]
 How to merge
@@ -1196,10 +1197,10 @@ linkgit:git-merge[1]:
 $ git merge branchname
 -------------------------------------------------
 
-merges the development in the branch "branchname" into the current
+merges the development in the branch `branchname` into the current
 branch.
 
-A merge is made by combining the changes made in "branchname" and the
+A merge is made by combining the changes made in `branchname` and the
 changes made up to the latest commit in your current branch since
 their histories forked. The work tree is overwritten by the result of
 the merge when this combining is done cleanly, or overwritten by a
@@ -1321,7 +1322,7 @@ that part is not conflicting and is not shown.  Same for stage 3).
 
 The diff above shows the differences between the working-tree version of
 file.txt and the stage 2 and stage 3 versions.  So instead of preceding
-each line by a single "+" or "-", it now uses two columns: the first
+each line by a single `+` or `-`, it now uses two columns: the first
 column is used for differences between the first parent and the working
 directory copy, and the second for differences between the second parent
 and the working directory copy.  (See the "COMBINED DIFF FORMAT" section
@@ -1602,7 +1603,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
 
 You will see informational messages on dangling objects. They are objects
 that still exist in the repository but are no longer referenced by any of
-your branches, and can (and will) be removed after a while with "gc".
+your branches, and can (and will) be removed after a while with `gc`.
 You can run `git fsck --no-dangling` to suppress these messages, and still
 view real errors.
 
@@ -1614,9 +1615,9 @@ Recovering lost changes
 Reflogs
 ^^^^^^^
 
-Say you modify a branch with +linkgit:git-reset[1] \--hard+, and then
-realize that the branch was the only reference you had to that point in
-history.
+Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
+and then realize that the branch was the only reference you had to
+that point in history.
 
 Fortunately, Git also keeps a log, called a "reflog", of all the
 previous values of each branch.  So in this case you can still find the
@@ -1627,8 +1628,8 @@ $ git log master@{1}
 -------------------------------------------------
 
 This lists the commits reachable from the previous version of the
-"master" branch head.  This syntax can be used with any Git command
-that accepts a commit, not just with git log.  Some other examples:
+`master` branch head.  This syntax can be used with any Git command
+that accepts a commit, not just with `git log`.  Some other examples:
 
 -------------------------------------------------
 $ git show master@{2}		# See where the branch pointed 2,
@@ -1732,8 +1733,8 @@ one step:
 $ git pull origin master
 -------------------------------------------------
 
-In fact, if you have "master" checked out, then this branch has been
-configured by "git clone" to get changes from the HEAD branch of the
+In fact, if you have `master` checked out, then this branch has been
+configured by `git clone` to get changes from the HEAD branch of the
 origin repository.  So often you can
 accomplish the above with just a simple
 
@@ -1748,11 +1749,11 @@ the current branch.
 More generally, a branch that is created from a remote-tracking branch
 will pull
 by default from that branch.  See the descriptions of the
-branch.<name>.remote and branch.<name>.merge options in
+`branch.<name>.remote` and `branch.<name>.merge` options in
 linkgit:git-config[1], and the discussion of the `--track` option in
 linkgit:git-checkout[1], to learn how to control these defaults.
 
-In addition to saving you keystrokes, "git pull" also helps you by
+In addition to saving you keystrokes, `git pull` also helps you by
 producing a default commit message documenting the branch and
 repository that you pulled from.
 
@@ -1760,7 +1761,7 @@ repository that you pulled from.
 <<fast-forwards,fast-forward>>; instead, your branch will just be
 updated to point to the latest commit from the upstream branch.)
 
-The `git pull` command can also be given "." as the "remote" repository,
+The `git pull` command can also be given `.` as the "remote" repository,
 in which case it just merges in a branch from the current repository; so
 the commands
 
@@ -1785,7 +1786,7 @@ $ git format-patch origin
 -------------------------------------------------
 
 will produce a numbered series of files in the current directory, one
-for each patch in the current branch but not in origin/HEAD.
+for each patch in the current branch but not in `origin/HEAD`.
 
 `git format-patch` can include an initial "cover letter". You can insert
 commentary on individual patches after the three dash line which
@@ -1807,7 +1808,7 @@ Importing patches to a project
 Git also provides a tool called linkgit:git-am[1] (am stands for
 "apply mailbox"), for importing such an emailed series of patches.
 Just save all of the patch-containing messages, in order, into a
-single mailbox file, say "patches.mbox", then run
+single mailbox file, say `patches.mbox`, then run
 
 -------------------------------------------------
 $ git am -3 patches.mbox
@@ -1815,7 +1816,7 @@ $ git am -3 patches.mbox
 
 Git will apply each patch in order; if any conflicts are found, it
 will stop, and you can fix the conflicts as described in
-"<<resolving-a-merge,Resolving a merge>>".  (The "-3" option tells
+"<<resolving-a-merge,Resolving a merge>>".  (The `-3` option tells
 Git to perform a merge; if you would prefer it just to abort and
 leave your tree and index untouched, you may omit that option.)
 
@@ -1891,7 +1892,7 @@ We explain how to do this in the following sections.
 Setting up a public repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Assume your personal repository is in the directory ~/proj.  We
+Assume your personal repository is in the directory `~/proj`.  We
 first create a new clone of the repository and tell `git daemon` that it
 is meant to be public:
 
@@ -1901,10 +1902,10 @@ $ touch proj.git/git-daemon-export-ok
 -------------------------------------------------
 
 The resulting directory proj.git contains a "bare" git repository--it is
-just the contents of the ".git" directory, without any files checked out
+just the contents of the `.git` directory, without any files checked out
 around it.
 
-Next, copy proj.git to the server where you plan to host the
+Next, copy `proj.git` to the server where you plan to host the
 public repository.  You can use scp, rsync, or whatever is most
 convenient.
 
@@ -1915,8 +1916,8 @@ Exporting a Git repository via the Git protocol
 This is the preferred method.
 
 If someone else administers the server, they should tell you what
-directory to put the repository in, and what git:// URL it will appear
-at.  You can then skip to the section
+directory to put the repository in, and what `git://` URL it will
+appear at.  You can then skip to the section
 "<<pushing-changes-to-a-public-repository,Pushing changes to a public
 repository>>", below.
 
@@ -1951,7 +1952,7 @@ $ mv hooks/post-update.sample hooks/post-update
 (For an explanation of the last two lines, see
 linkgit:git-update-server-info[1] and linkgit:githooks[5].)
 
-Advertise the URL of proj.git.  Anybody else should then be able to
+Advertise the URL of `proj.git`.  Anybody else should then be able to
 clone or pull from that URL, for example with a command line like:
 
 -------------------------------------------------
@@ -1974,8 +1975,8 @@ access, which you will need to update the public repository with the
 latest changes created in your private repository.
 
 The simplest way to do this is using linkgit:git-push[1] and ssh; to
-update the remote branch named "master" with the latest state of your
-branch named "master", run
+update the remote branch named `master` with the latest state of your
+branch named `master`, run
 
 -------------------------------------------------
 $ git push ssh://yourserver.com/~you/proj.git master:master
@@ -1991,7 +1992,7 @@ As with `git fetch`, `git push` will complain if this does not result in a
 <<fast-forwards,fast-forward>>; see the following section for details on
 handling this case.
 
-Note that the target of a "push" is normally a
+Note that the target of a `push` is normally a
 <<def_bare_repository,bare>> repository.  You can also push to a
 repository that has a checked-out working tree, but the working tree
 will not be updated by the push.  This may lead to unexpected results if
@@ -2018,9 +2019,9 @@ which lets you do the same push with just
 $ git push public-repo master
 -------------------------------------------------
 
-See the explanations of the remote.<name>.url, branch.<name>.remote,
-and remote.<name>.push options in linkgit:git-config[1] for
-details.
+See the explanations of the `remote.<name>.url`,
+`branch.<name>.remote`, and `remote.<name>.push` options in
+linkgit:git-config[1] for details.
 
 [[forcing-push]]
 What to do when a push fails
@@ -2155,7 +2156,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see
 
 Now create the branches in which you are going to work; these start out
 at the current tip of origin/master branch, and should be set up (using
-the --track option to linkgit:git-branch[1]) to merge changes in from
+the `--track` option to linkgit:git-branch[1]) to merge changes in from
 Linus by default.
 
 -------------------------------------------------
@@ -2174,7 +2175,7 @@ Important note!  If you have any local changes in these branches, then
 this merge will create a commit object in the history (with no local
 changes Git will simply do a "fast-forward" merge).  Many people dislike
 the "noise" that this creates in the Linux history, so you should avoid
-doing this capriciously in the "release" branch, as these noisy commits
+doing this capriciously in the `release` branch, as these noisy commits
 will become part of the permanent history when you ask Linus to pull
 from the release branch.
 
@@ -2216,7 +2217,7 @@ patches), and create a new branch from a recent stable tag of
 Linus's branch. Picking a stable base for your branch will:
 1) help you: by avoiding inclusion of unrelated and perhaps lightly
 tested changes
-2) help future bug hunters that use "git bisect" to find problems
+2) help future bug hunters that use `git bisect` to find problems
 
 -------------------------------------------------
 $ git checkout -b speed-up-spinlocks v2.6.35
@@ -2241,9 +2242,9 @@ It is unlikely that you would have any conflicts here ... but you might if you
 spent a while on this step and had also pulled new versions from upstream.
 
 Some time later when enough time has passed and testing done, you can pull the
-same branch into the "release" tree ready to go upstream.  This is where you
+same branch into the `release` tree ready to go upstream.  This is where you
 see the value of keeping each patch (or patch series) in its own branch.  It
-means that the patches can be moved into the "release" tree in any order.
+means that the patches can be moved into the `release` tree in any order.
 
 -------------------------------------------------
 $ git checkout release && git pull . speed-up-spinlocks
@@ -2276,7 +2277,7 @@ If it has been merged, then there will be no output.)
 
 Once a patch completes the great cycle (moving from test to release,
 then pulled by Linus, and finally coming back into your local
-"origin/master" branch), the branch for this change is no longer needed.
+`origin/master` branch), the branch for this change is no longer needed.
 You detect this when the output from:
 
 -------------------------------------------------
@@ -2291,8 +2292,8 @@ $ git branch -d branchname
 
 Some changes are so trivial that it is not necessary to create a separate
 branch and then merge into each of the test and release branches.  For
-these changes, just apply directly to the "release" branch, and then
-merge that into the "test" branch.
+these changes, just apply directly to the `release` branch, and then
+merge that into the `test` branch.
 
 To create diffstat and shortlog summaries of changes to include in a "please
 pull" request to Linus you can use:
@@ -2467,8 +2468,8 @@ you are rewriting history.
 Keeping a patch series up to date using git rebase
 --------------------------------------------------
 
-Suppose that you create a branch "mywork" on a remote-tracking branch
-"origin", and create some commits on top of it:
+Suppose that you create a branch `mywork` on a remote-tracking branch
+`origin`, and create some commits on top of it:
 
 -------------------------------------------------
 $ git checkout -b mywork origin
@@ -2480,7 +2481,7 @@ $ git commit
 -------------------------------------------------
 
 You have performed no merges into mywork, so it is just a simple linear
-sequence of patches on top of "origin":
+sequence of patches on top of `origin`:
 
 ................................................
  o--o--O <-- origin
@@ -2489,7 +2490,7 @@ sequence of patches on top of "origin":
 ................................................
 
 Some more interesting work has been done in the upstream project, and
-"origin" has advanced:
+`origin` has advanced:
 
 ................................................
  o--o--O--o--o--o <-- origin
@@ -2497,7 +2498,7 @@ Some more interesting work has been done in the upstream project, and
          a--b--c <-- mywork
 ................................................
 
-At this point, you could use "pull" to merge your changes back in;
+At this point, you could use `pull` to merge your changes back in;
 the result would create a new merge commit, like this:
 
 ................................................
@@ -2516,7 +2517,7 @@ $ git rebase origin
 -------------------------------------------------
 
 This will remove each of your commits from mywork, temporarily saving
-them as patches (in a directory named ".git/rebase-apply"), update mywork to
+them as patches (in a directory named `.git/rebase-apply`), update mywork to
 point at the latest version of origin, then apply each of the saved
 patches to the new mywork.  The result will look like:
 
@@ -2780,10 +2781,10 @@ arbitrary name:
 $ git fetch origin todo:my-todo-work
 -------------------------------------------------
 
-The first argument, "origin", just tells Git to fetch from the
+The first argument, `origin`, just tells Git to fetch from the
 repository you originally cloned from.  The second argument tells Git
-to fetch the branch named "todo" from the remote repository, and to
-store it locally under the name refs/heads/my-todo-work.
+to fetch the branch named `todo` from the remote repository, and to
+store it locally under the name `refs/heads/my-todo-work`.
 
 You can also fetch branches from other repositories; so
 
@@ -2791,8 +2792,8 @@ You can also fetch branches from other repositories; so
 $ git fetch git://example.com/proj.git master:example-master
 -------------------------------------------------
 
-will create a new branch named "example-master" and store in it the
-branch named "master" from the repository at the given URL.  If you
+will create a new branch named `example-master` and store in it the
+branch named `master` from the repository at the given URL.  If you
 already have a branch named example-master, it will attempt to
 <<fast-forwards,fast-forward>> to the commit given by example.com's
 master branch.  In more detail:
@@ -2801,7 +2802,7 @@ master branch.  In more detail:
 git fetch and fast-forwards
 ---------------------------
 
-In the previous example, when updating an existing branch, "git fetch"
+In the previous example, when updating an existing branch, `git fetch`
 checks to make sure that the most recent commit on the remote
 branch is a descendant of the most recent commit on your copy of the
 branch before updating your copy of the branch to point at the new
@@ -2827,11 +2828,11 @@ resulting in a situation like:
             o--o--o <-- new head of the branch
 ................................................
 
-In this case, "git fetch" will fail, and print out a warning.
+In this case, `git fetch` will fail, and print out a warning.
 
 In that case, you can still force Git to update to the new head, as
 described in the following section.  However, note that in the
-situation above this may mean losing the commits labeled "a" and "b",
+situation above this may mean losing the commits labeled `a` and `b`,
 unless you've already created a reference of your own pointing to
 them.
 
@@ -2846,7 +2847,7 @@ descendant of the old head, you may force the update with:
 $ git fetch git://example.com/proj.git +master:refs/remotes/example/master
 -------------------------------------------------
 
-Note the addition of the "+" sign.  Alternatively, you can use the "-f"
+Note the addition of the `+` sign.  Alternatively, you can use the `-f`
 flag to force updates of all the fetched branches, as in:
 
 -------------------------------------------------
@@ -2860,7 +2861,7 @@ may be lost, as we saw in the previous section.
 Configuring remote-tracking branches
 ------------------------------------
 
-We saw above that "origin" is just a shortcut to refer to the
+We saw above that `origin` is just a shortcut to refer to the
 repository that you originally cloned from.  This information is
 stored in Git configuration variables, which you can see using
 linkgit:git-config[1]:
@@ -2969,7 +2970,7 @@ Commit Object
 ~~~~~~~~~~~~~
 
 The "commit" object links a physical state of a tree with a description
-of how we got there and why.  Use the --pretty=raw option to
+of how we got there and why.  Use the `--pretty=raw` option to
 linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
 commit:
 
@@ -3011,7 +3012,7 @@ of the tree referred to by this commit with the trees associated with
 its parents.  In particular, Git does not attempt to record file renames
 explicitly, though it can identify cases where the existence of the same
 file data at changing paths suggests a rename.  (See, for example, the
--M option to linkgit:git-diff[1]).
+`-M` option to linkgit:git-diff[1]).
 
 A commit is usually created by linkgit:git-commit[1], which creates a
 commit whose parent is normally the current HEAD, and whose tree is
@@ -3062,7 +3063,7 @@ Blob Object
 ~~~~~~~~~~~
 
 You can use linkgit:git-show[1] to examine the contents of a blob; take,
-for example, the blob in the entry for "COPYING" from the tree above:
+for example, the blob in the entry for `COPYING` from the tree above:
 
 ------------------------------------------------
 $ git show 6ff87c4664
@@ -3145,14 +3146,14 @@ nLE/L9aUXdWeTFPron96DLA=
 See the linkgit:git-tag[1] command to learn how to create and verify tag
 objects.  (Note that linkgit:git-tag[1] can also be used to create
 "lightweight tags", which are not tag objects at all, but just simple
-references whose names begin with "refs/tags/").
+references whose names begin with `refs/tags/`).
 
 [[pack-files]]
 How Git stores objects efficiently: pack files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Newly created objects are initially created in a file named after the
-object's SHA-1 hash (stored in .git/objects).
+object's SHA-1 hash (stored in `.git/objects`).
 
 Unfortunately this system becomes inefficient once a project has a
 lot of objects.  Try this on an old project:
@@ -3193,9 +3194,9 @@ $ git prune
 
 to remove any of the "loose" objects that are now contained in the
 pack.  This will also remove any unreferenced objects (which may be
-created when, for example, you use "git reset" to remove a commit).
+created when, for example, you use `git reset` to remove a commit).
 You can verify that the loose objects are gone by looking at the
-.git/objects directory or by running
+`.git/objects` directory or by running
 
 ------------------------------------------------
 $ git count-objects
@@ -3222,7 +3223,7 @@ branch still exists, as does everything it pointed to. The branch
 pointer itself just doesn't, since you replaced it with another one.
 
 There are also other situations that cause dangling objects. For
-example, a "dangling blob" may arise because you did a "git add" of a
+example, a "dangling blob" may arise because you did a `git add` of a
 file, but then, before you actually committed it and made it part of the
 bigger picture, you changed something else in that file and committed
 that *updated* thing--the old state that you added originally ends up
@@ -3265,14 +3266,14 @@ $ git show <dangling-blob/tree-sha-goes-here>
 ------------------------------------------------
 
 to show what the contents of the blob were (or, for a tree, basically
-what the "ls" for that directory was), and that may give you some idea
+what the `ls` for that directory was), and that may give you some idea
 of what the operation was that left that dangling object.
 
 Usually, dangling blobs and trees aren't very interesting. They're
 almost always the result of either being a half-way mergebase (the blob
 will often even have the conflict markers from a merge in it, if you
 have had conflicting merges that you fixed up by hand), or simply
-because you interrupted a "git fetch" with ^C or something like that,
+because you interrupted a `git fetch` with ^C or something like that,
 leaving _some_ of the new objects in the object database, but just
 dangling and useless.
 
@@ -3283,16 +3284,16 @@ state, you can just prune all unreachable objects:
 $ git prune
 ------------------------------------------------
 
-and they'll be gone. But you should only run "git prune" on a quiescent
+and they'll be gone. But you should only run `git prune` on a quiescent
 repository--it's kind of like doing a filesystem fsck recovery: you
 don't want to do that while the filesystem is mounted.
 
-(The same is true of "git fsck" itself, btw, but since
+(The same is true of `git fsck` itself, btw, but since
 `git fsck` never actually *changes* the repository, it just reports
 on what it found, `git fsck` itself is never 'dangerous' to run.
 Running it while somebody is actually changing the repository can cause
 confusing and scary messages, but it won't actually do anything bad. In
-contrast, running "git prune" while somebody is actively changing the
+contrast, running `git prune` while somebody is actively changing the
 repository is a *BAD* idea).
 
 [[recovering-from-repository-corruption]]
@@ -3330,7 +3331,7 @@ missing blob 4b9458b3786228369c63936db65827de3cc06200
 Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
 points to it.  If you could find just one copy of that missing blob
 object, possibly in some other repository, you could move it into
-.git/objects/4b/9458b3... and be done.  Suppose you can't.  You can
+`.git/objects/4b/9458b3...` and be done.  Suppose you can't.  You can
 still examine the tree that pointed to it with linkgit:git-ls-tree[1],
 which might output something like:
 
@@ -3345,10 +3346,10 @@ $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
 ------------------------------------------------
 
 So now you know that the missing blob was the data for a file named
-"myfile".  And chances are you can also identify the directory--let's
-say it's in "somedirectory".  If you're lucky the missing copy might be
+`myfile`.  And chances are you can also identify the directory--let's
+say it's in `somedirectory`.  If you're lucky the missing copy might be
 the same as the copy you have checked out in your working tree at
-"somedirectory/myfile"; you can test whether that's right with
+`somedirectory/myfile`; you can test whether that's right with
 linkgit:git-hash-object[1]:
 
 ------------------------------------------------
@@ -3403,7 +3404,7 @@ $ git hash-object -w <recreated-file>
 
 and your repository is good again!
 
-(Btw, you could have ignored the fsck, and started with doing a
+(Btw, you could have ignored the `fsck`, and started with doing a
 
 ------------------------------------------------
 $ git log --raw --all
@@ -3417,7 +3418,7 @@ just missing one particular blob version.
 The index
 -----------
 
-The index is a binary file (generally kept in .git/index) containing a
+The index is a binary file (generally kept in `.git/index`) containing a
 sorted list of path names, each with permissions and the SHA-1 of a blob
 object; linkgit:git-ls-files[1] can show you the contents of the index:
 
@@ -3557,7 +3558,7 @@ $ ls -a
 
 The `git submodule add <repo> <path>` command does a couple of things:
 
-- It clones the submodule from <repo> to the given <path> under the
+- It clones the submodule from `<repo>` to the given `<path>` under the
   current directory and by default checks out the master branch.
 - It adds the submodule's clone path to the linkgit:gitmodules[5] file and
   adds this file to the index, ready to be committed.
@@ -3685,11 +3686,11 @@ Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path
 
 In older Git versions it could be easily forgotten to commit new or modified
 files in a submodule, which silently leads to similar problems as not pushing
-the submodule changes. Starting with Git 1.7.0 both "git status" and "git diff"
+the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
 in the superproject show submodules as modified when they contain new or
-modified files to protect against accidentally committing such a state. "git
-diff" will also add a "-dirty" to the work tree side when generating patch
-output or used with the --submodule option:
+modified files to protect against accidentally committing such a state. `git
+diff` will also add a `-dirty` to the work tree side when generating patch
+output or used with the `--submodule` option:
 
 -------------------------------------------------
 $ git diff
@@ -3863,7 +3864,7 @@ or, if you want to check out all of the index, use `-a`.
 
 NOTE! `git checkout-index` normally refuses to overwrite old files, so
 if you have an old version of the tree already checked out, you will
-need to use the "-f" flag ('before' the "-a" flag or the filename) to
+need to use the `-f` flag ('before' the `-a` flag or the filename) to
 'force' the checkout.
 
 
@@ -3874,7 +3875,7 @@ from one representation to the other:
 Tying it all together
 ~~~~~~~~~~~~~~~~~~~~~
 
-To commit a tree you have instantiated with "git write-tree", you'd
+To commit a tree you have instantiated with `git write-tree`, you'd
 create a "commit" object that refers to that tree and the history
 behind it--most notably the "parent" commits that preceded it in
 history.
@@ -4135,8 +4136,9 @@ As a result, the general consistency of an object can always be tested
 independently of the contents or the type of the object: all objects can
 be validated by verifying that (a) their hashes match the content of the
 file and (b) the object successfully inflates to a stream of bytes that
-forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal
-size> {plus} <byte\0> {plus} <binary object data>.
+forms a sequence of
+`<ascii type without space> + <space> + <ascii decimal size> +
+<byte\0> + <binary object data>`.
 
 The structured objects can further have their structure and
 connectivity to other objects verified. This is generally done with
@@ -4615,10 +4617,10 @@ Think about how to create a clear chapter dependency graph that will
 allow people to get to important topics without necessarily reading
 everything in between.
 
-Scan Documentation/ for other stuff left out; in particular:
+Scan `Documentation/` for other stuff left out; in particular:
 
 - howto's
-- some of technical/?
+- some of `technical/`?
 - hooks
 - list of commands in linkgit:git[1]
 
-- 
1.8.1.336.g94702dd

[PATCH v5] user-manual: Standardize backtick quoting

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I tried to always use backticks for:
* Paths and filenames (e.g. `.git/config`)
* Compound refs (e.g. `origin/HEAD`)
* Git commands (e.g. `git log`)
* Command arguments (e.g. `--pretty`)
* URLs (e.g. `git://`), as a subset of command arguments
* Special characters (e.g. `+` in diffs).
* Config options (e.g. `branch.<name>.remote`)

Branch and tag names are sometimes set off with double quotes,
sometimes set off with backticks, and sometimes left bare.  I tried to
judge when the intention was introducing new terms or conventions
(double quotes), to reference a recently used command argument
(backticks), or to reference the abstract branch/commit (left bare).
Obviously these are not particularly crisp definitions, so my
decisions are fairly arbitrary ;).  When a reference had already been
introduced, I changed further double-quoted instances to backticked
instances.

When new backticks increased the length of a line beyond others in
that block, I re-wrapped blocks to 72 columns.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
This patch was not present in v4.  Changes from v3:

* Rebased onto v1.8.2-rc1, after both my earlier cleanups and the
  git/Git/GIT standardization from 2de9b71 (Documentation: the name of
  the system is 'Git', not 'git', 2013-01-21).

It's probably easier to review this if you just apply the patch and
then go back through with --word-diff ;).

 Documentation/user-manual.txt | 286 +++++++++++++++++++++---------------------
 1 file changed, 144 insertions(+), 142 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5f36f81..0170a23 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -19,7 +19,7 @@ Further chapters cover more specialized topics.
 
 Comprehensive reference documentation is available through the man
 pages, or linkgit:git-help[1] command.  For example, for the command
-"git clone <repo>", you can either use:
+`git clone <repo>`, you can either use:
 
 ------------------------------------------------
 $ man git-clone
@@ -66,11 +66,11 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
 The initial clone may be time-consuming for a large project, but you
 will only need to clone once.
 
-The clone command creates a new directory named after the project ("git"
-or "linux-2.6" in the examples above).  After you cd into this
+The clone command creates a new directory named after the project (`git`
+or `linux-2.6` in the examples above).  After you cd into this
 directory, you will see that it contains a copy of the project files,
 called the <<def_working_tree,working tree>>, together with a special
-top-level directory named ".git", which contains all the information
+top-level directory named `.git`, which contains all the information
 about the history of the project.
 
 [[how-to-check-out]]
@@ -188,7 +188,7 @@ As you can see, a commit shows who made the latest change, what they
 did, and why.
 
 Every commit has a 40-hexdigit id, sometimes called the "object name" or the
-"SHA-1 id", shown on the first line of the "git show" output.  You can usually
+"SHA-1 id", shown on the first line of the `git show` output.  You can usually
 refer to a commit by a shorter name, such as a tag or a branch name, but this
 longer name can also be useful.  Most importantly, it is a globally unique
 name for this commit: so if you tell somebody else the object name (for
@@ -268,35 +268,35 @@ Manipulating branches
 Creating, deleting, and modifying branches is quick and easy; here's
 a summary of the commands:
 
-git branch::
+`git branch`::
 	list all branches
-git branch <branch>::
-	create a new branch named <branch>, referencing the same
+`git branch <branch>`::
+	create a new branch named `<branch>`, referencing the same
 	point in history as the current branch
-git branch <branch> <start-point>::
-	create a new branch named <branch>, referencing
-	<start-point>, which may be specified any way you like,
+`git branch <branch> <start-point>`::
+	create a new branch named `<branch>`, referencing
+	`<start-point>`, which may be specified any way you like,
 	including using a branch name or a tag name
-git branch -d <branch>::
-	delete the branch <branch>; if the branch you are deleting
+`git branch -d <branch>`::
+	delete the branch `<branch>`; if the branch you are deleting
 	points to a commit which is not reachable from the current
 	branch, this command will fail with a warning.
-git branch -D <branch>::
+`git branch -D <branch>`::
 	even if the branch points to a commit not reachable
 	from the current branch, you may know that that commit
 	is still reachable from some other branch or tag.  In that
 	case it is safe to use this command to force Git to delete
 	the branch.
-git checkout <branch>::
-	make the current branch <branch>, updating the working
-	directory to reflect the version referenced by <branch>
-git checkout -b <new> <start-point>::
-	create a new branch <new> referencing <start-point>, and
+`git checkout <branch>`::
+	make the current branch `<branch>`, updating the working
+	directory to reflect the version referenced by `<branch>`
+`git checkout -b <new> <start-point>`::
+	create a new branch `<new>` referencing `<start-point>`, and
 	check it out.
 
 The special symbol "HEAD" can always be used to refer to the current
-branch.  In fact, Git uses a file named "HEAD" in the .git directory to
-remember which branch is current:
+branch.  In fact, Git uses a file named `HEAD` in the `.git` directory
+to remember which branch is current:
 
 ------------------------------------------------
 $ cat .git/HEAD
@@ -346,7 +346,7 @@ of the HEAD in the repository that you cloned from.  That repository
 may also have had other branches, though, and your local repository
 keeps branches which track each of those remote branches, called
 remote-tracking branches, which you
-can view using the "-r" option to linkgit:git-branch[1]:
+can view using the `-r` option to linkgit:git-branch[1]:
 
 ------------------------------------------------
 $ git branch -r
@@ -364,7 +364,7 @@ In this example, "origin" is called a remote repository, or "remote"
 for short. The branches of this repository are called "remote
 branches" from our point of view. The remote-tracking branches listed
 above were created based on the remote branches at clone time and will
-be updated by "git fetch" (hence "git pull") and "git push". See
+be updated by `git fetch` (hence `git pull`) and `git push`. See
 <<Updating-a-repository-With-git-fetch>> for details.
 
 You might want to build on one of these remote-tracking branches
@@ -374,7 +374,7 @@ on a branch of your own, just as you would for a tag:
 $ git checkout -b my-todo-copy origin/todo
 ------------------------------------------------
 
-You can also check out "origin/todo" directly to examine it or
+You can also check out `origin/todo` directly to examine it or
 write a one-off patch.  See <<detached-head,detached head>>.
 
 Note that the name "origin" is just the name that Git uses by default
@@ -386,17 +386,17 @@ Naming branches, tags, and other references
 
 Branches, remote-tracking branches, and tags are all references to
 commits.  All references are named with a slash-separated path name
-starting with "refs"; the names we've been using so far are actually
+starting with `refs`; the names we've been using so far are actually
 shorthand:
 
-	- The branch "test" is short for "refs/heads/test".
-	- The tag "v2.6.18" is short for "refs/tags/v2.6.18".
-	- "origin/master" is short for "refs/remotes/origin/master".
+	- The branch `test` is short for `refs/heads/test`.
+	- The tag `v2.6.18` is short for `refs/tags/v2.6.18`.
+	- `origin/master` is short for `refs/remotes/origin/master`.
 
 The full name is occasionally useful if, for example, there ever
 exists a tag and a branch with the same name.
 
-(Newly created refs are actually stored in the .git/refs directory,
+(Newly created refs are actually stored in the `.git/refs` directory,
 under the path given by their name.  However, for efficiency reasons
 they may also be packed together in a single file; see
 linkgit:git-pack-refs[1]).
@@ -418,7 +418,7 @@ Eventually the developer cloned from will do additional work in her
 repository, creating new commits and advancing the branches to point
 at the new commits.
 
-The command "git fetch", with no arguments, will update all of the
+The command `git fetch`, with no arguments, will update all of the
 remote-tracking branches to the latest version found in her
 repository.  It will not touch any of your own branches--not even the
 "master" branch that was created for you on clone.
@@ -438,7 +438,7 @@ $ git fetch linux-nfs
 -------------------------------------------------
 
 New remote-tracking branches will be stored under the shorthand name
-that you gave "git remote add", in this case linux-nfs:
+that you gave `git remote add`, in this case `linux-nfs`:
 
 -------------------------------------------------
 $ git branch -r
@@ -446,10 +446,10 @@ linux-nfs/master
 origin/master
 -------------------------------------------------
 
-If you run "git fetch <remote>" later, the remote-tracking branches for the
-named <remote> will be updated.
+If you run `git fetch <remote>` later, the remote-tracking branches
+for the named `<remote>` will be updated.
 
-If you examine the file .git/config, you will see that Git has added
+If you examine the file `.git/config`, you will see that Git has added
 a new stanza:
 
 -------------------------------------------------
@@ -462,7 +462,7 @@ $ cat .git/config
 -------------------------------------------------
 
 This is what causes Git to track the remote's branches; you may modify
-or delete these configuration options by editing .git/config with a
+or delete these configuration options by editing `.git/config` with a
 text editor.  (See the "CONFIGURATION FILE" section of
 linkgit:git-config[1] for details.)
 
@@ -499,7 +499,7 @@ Bisecting: 3537 revisions left to test after this
 [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
 -------------------------------------------------
 
-If you run "git branch" at this point, you'll see that Git has
+If you run `git branch` at this point, you'll see that Git has
 temporarily moved you in "(no branch)". HEAD is now detached from any
 branch and points directly to a commit (with commit id 65934...) that
 is reachable from "master" but not from v2.6.18. Compile and test it,
@@ -545,11 +545,11 @@ id, and check it out with:
 $ git reset --hard fb47ddb2db...
 -------------------------------------------------
 
-then test, run "bisect good" or "bisect bad" as appropriate, and
+then test, run `bisect good` or `bisect bad` as appropriate, and
 continue.
 
-Instead of "git bisect visualize" and then "git reset --hard
-fb47ddb2db...", you might just want to tell Git that you want to skip
+Instead of `git bisect visualize` and then `git reset --hard
+fb47ddb2db...`, you might just want to tell Git that you want to skip
 the current commit:
 
 -------------------------------------------------
@@ -561,8 +561,8 @@ bad one between some first skipped commits and a later bad commit.
 
 There are also ways to automate the bisecting process if you have a
 test script that can tell a good from a bad commit. See
-linkgit:git-bisect[1] for more information about this and other "git
-bisect" features.
+linkgit:git-bisect[1] for more information about this and other `git
+bisect` features.
 
 [[naming-commits]]
 Naming commits
@@ -591,7 +591,7 @@ $ git show HEAD~4   # the great-great-grandparent
 -------------------------------------------------
 
 Recall that merge commits may have more than one parent; by default,
-^ and ~ follow the first parent listed in the commit, but you can
+`^` and `~` follow the first parent listed in the commit, but you can
 also choose:
 
 -------------------------------------------------
@@ -640,7 +640,7 @@ running
 $ git tag stable-1 1b2e1d63ff
 -------------------------------------------------
 
-You can use stable-1 to refer to the commit 1b2e1d63ff.
+You can use `stable-1` to refer to the commit 1b2e1d63ff.
 
 This creates a "lightweight" tag.  If you would also like to include a
 comment with the tag, and possibly sign it cryptographically, then you
@@ -669,7 +669,7 @@ $ git log -S'foo()'	# commits which add or remove any file data
 -------------------------------------------------
 
 And of course you can combine all of these; the following finds
-commits since v2.5 which touch the Makefile or any file under fs:
+commits since v2.5 which touch the `Makefile` or any file under `fs`:
 
 -------------------------------------------------
 $ git log v2.5.. Makefile fs/
@@ -681,7 +681,7 @@ You can also ask git log to show patches:
 $ git log -p
 -------------------------------------------------
 
-See the "--pretty" option in the linkgit:git-log[1] man page for more
+See the `--pretty` option in the linkgit:git-log[1] man page for more
 display options.
 
 Note that git log starts with the most recent commit and works
@@ -742,8 +742,8 @@ Examples
 Counting the number of commits on a branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Suppose you want to know how many commits you've made on "mybranch"
-since it diverged from "origin":
+Suppose you want to know how many commits you've made on `mybranch`
+since it diverged from `origin`:
 
 -------------------------------------------------
 $ git log --pretty=oneline origin..mybranch | wc -l
@@ -780,7 +780,7 @@ $ git rev-list master
 e05db0fd4f31dde7005f075a84f96b360d05984b
 -------------------------------------------------
 
-Or you could recall that the ... operator selects all commits
+Or you could recall that the `...` operator selects all commits
 contained reachable from either one reference or the other but not
 both; so
 
@@ -880,7 +880,7 @@ Showing commits unique to a given branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Suppose you would like to see all the commits reachable from the branch
-head named "master" but not from any other head in your repository.
+head named `master` but not from any other head in your repository.
 
 We can list all the heads in this repository with
 linkgit:git-show-ref[1]:
@@ -894,7 +894,7 @@ a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
 -------------------------------------------------
 
-We can get just the branch-head names, and remove "master", with
+We can get just the branch-head names, and remove `master`, with
 the help of the standard utilities cut and grep:
 
 -------------------------------------------------
@@ -939,7 +939,7 @@ is preceded by `project/`.  The output file format is inferred from
 the output file extension if possible, see linkgit:git-archive[1] for
 details.
 
-Versions of Git older than 1.7.7 don't know about the 'tar.gz' format,
+Versions of Git older than 1.7.7 don't know about the `tar.gz` format,
 you'll need to use gzip explicitly:
 
 -------------------------------------------------
@@ -1062,7 +1062,7 @@ at step 3, Git maintains a snapshot of the tree's contents in a
 special staging area called "the index."
 
 At the beginning, the content of the index will be identical to
-that of the HEAD.  The command "git diff --cached", which shows
+that of the HEAD.  The command `git diff --cached`, which shows
 the difference between the HEAD and the index, should therefore
 produce no output at that point.
 
@@ -1101,7 +1101,7 @@ $ git diff
 
 shows the difference between the working tree and the index file.
 
-Note that "git add" always adds just the current contents of a file
+Note that `git add` always adds just the current contents of a file
 to the index; further changes to the same file will be ignored unless
 you run `git add` on the file again.
 
@@ -1172,8 +1172,9 @@ annoying to have these untracked files lying around; e.g. they make
 `git add .` practically useless, and they keep showing up in the output of
 `git status`.
 
-You can tell Git to ignore certain files by creating a file called .gitignore
-in the top level of your working directory, with contents such as:
+You can tell Git to ignore certain files by creating a file called
+`.gitignore` in the top level of your working directory, with contents
+such as:
 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.
@@ -1197,10 +1198,10 @@ for other users who clone your repository.
 
 If you wish the exclude patterns to affect only certain repositories
 (instead of every repository for a given project), you may instead put
-them in a file in your repository named .git/info/exclude, or in any file
-specified by the `core.excludesfile` configuration variable.  Some Git
-commands can also take exclude patterns directly on the command line.
-See linkgit:gitignore[5] for the details.
+them in a file in your repository named `.git/info/exclude`, or in any
+file specified by the `core.excludesfile` configuration variable.
+Some Git commands can also take exclude patterns directly on the
+command line.  See linkgit:gitignore[5] for the details.
 
 [[how-to-merge]]
 How to merge
@@ -1213,10 +1214,10 @@ linkgit:git-merge[1]:
 $ git merge branchname
 -------------------------------------------------
 
-merges the development in the branch "branchname" into the current
+merges the development in the branch `branchname` into the current
 branch.
 
-A merge is made by combining the changes made in "branchname" and the
+A merge is made by combining the changes made in `branchname` and the
 changes made up to the latest commit in your current branch since
 their histories forked. The work tree is overwritten by the result of
 the merge when this combining is done cleanly, or overwritten by a
@@ -1338,7 +1339,7 @@ that part is not conflicting and is not shown.  Same for stage 3).
 
 The diff above shows the differences between the working-tree version of
 file.txt and the stage 2 and stage 3 versions.  So instead of preceding
-each line by a single "+" or "-", it now uses two columns: the first
+each line by a single `+` or `-`, it now uses two columns: the first
 column is used for differences between the first parent and the working
 directory copy, and the second for differences between the second parent
 and the working directory copy.  (See the "COMBINED DIFF FORMAT" section
@@ -1613,7 +1614,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
 
 You will see informational messages on dangling objects. They are objects
 that still exist in the repository but are no longer referenced by any of
-your branches, and can (and will) be removed after a while with "gc".
+your branches, and can (and will) be removed after a while with `gc`.
 You can run `git fsck --no-dangling` to suppress these messages, and still
 view real errors.
 
@@ -1625,9 +1626,9 @@ Recovering lost changes
 Reflogs
 ^^^^^^^
 
-Say you modify a branch with +linkgit:git-reset[1] \--hard+, and then
-realize that the branch was the only reference you had to that point in
-history.
+Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
+and then realize that the branch was the only reference you had to
+that point in history.
 
 Fortunately, Git also keeps a log, called a "reflog", of all the
 previous values of each branch.  So in this case you can still find the
@@ -1638,8 +1639,8 @@ $ git log master@{1}
 -------------------------------------------------
 
 This lists the commits reachable from the previous version of the
-"master" branch head.  This syntax can be used with any Git command
-that accepts a commit, not just with git log.  Some other examples:
+`master` branch head.  This syntax can be used with any Git command
+that accepts a commit, not just with `git log`.  Some other examples:
 
 -------------------------------------------------
 $ git show master@{2}		# See where the branch pointed 2,
@@ -1743,8 +1744,8 @@ one step:
 $ git pull origin master
 -------------------------------------------------
 
-In fact, if you have "master" checked out, then this branch has been
-configured by "git clone" to get changes from the HEAD branch of the
+In fact, if you have `master` checked out, then this branch has been
+configured by `git clone` to get changes from the HEAD branch of the
 origin repository.  So often you can
 accomplish the above with just a simple
 
@@ -1759,11 +1760,11 @@ the current branch.
 More generally, a branch that is created from a remote-tracking branch
 will pull
 by default from that branch.  See the descriptions of the
-branch.<name>.remote and branch.<name>.merge options in
+`branch.<name>.remote` and `branch.<name>.merge` options in
 linkgit:git-config[1], and the discussion of the `--track` option in
 linkgit:git-checkout[1], to learn how to control these defaults.
 
-In addition to saving you keystrokes, "git pull" also helps you by
+In addition to saving you keystrokes, `git pull` also helps you by
 producing a default commit message documenting the branch and
 repository that you pulled from.
 
@@ -1771,7 +1772,7 @@ repository that you pulled from.
 <<fast-forwards,fast-forward>>; instead, your branch will just be
 updated to point to the latest commit from the upstream branch.)
 
-The `git pull` command can also be given "." as the "remote" repository,
+The `git pull` command can also be given `.` as the "remote" repository,
 in which case it just merges in a branch from the current repository; so
 the commands
 
@@ -1796,7 +1797,7 @@ $ git format-patch origin
 -------------------------------------------------
 
 will produce a numbered series of files in the current directory, one
-for each patch in the current branch but not in origin/HEAD.
+for each patch in the current branch but not in `origin/HEAD`.
 
 `git format-patch` can include an initial "cover letter". You can insert
 commentary on individual patches after the three dash line which
@@ -1818,7 +1819,7 @@ Importing patches to a project
 Git also provides a tool called linkgit:git-am[1] (am stands for
 "apply mailbox"), for importing such an emailed series of patches.
 Just save all of the patch-containing messages, in order, into a
-single mailbox file, say "patches.mbox", then run
+single mailbox file, say `patches.mbox`, then run
 
 -------------------------------------------------
 $ git am -3 patches.mbox
@@ -1826,7 +1827,7 @@ $ git am -3 patches.mbox
 
 Git will apply each patch in order; if any conflicts are found, it
 will stop, and you can fix the conflicts as described in
-"<<resolving-a-merge,Resolving a merge>>".  (The "-3" option tells
+"<<resolving-a-merge,Resolving a merge>>".  (The `-3` option tells
 Git to perform a merge; if you would prefer it just to abort and
 leave your tree and index untouched, you may omit that option.)
 
@@ -1902,7 +1903,7 @@ We explain how to do this in the following sections.
 Setting up a public repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Assume your personal repository is in the directory ~/proj.  We
+Assume your personal repository is in the directory `~/proj`.  We
 first create a new clone of the repository and tell `git daemon` that it
 is meant to be public:
 
@@ -1912,10 +1913,10 @@ $ touch proj.git/git-daemon-export-ok
 -------------------------------------------------
 
 The resulting directory proj.git contains a "bare" git repository--it is
-just the contents of the ".git" directory, without any files checked out
+just the contents of the `.git` directory, without any files checked out
 around it.
 
-Next, copy proj.git to the server where you plan to host the
+Next, copy `proj.git` to the server where you plan to host the
 public repository.  You can use scp, rsync, or whatever is most
 convenient.
 
@@ -1926,8 +1927,8 @@ Exporting a Git repository via the Git protocol
 This is the preferred method.
 
 If someone else administers the server, they should tell you what
-directory to put the repository in, and what git:// URL it will appear
-at.  You can then skip to the section
+directory to put the repository in, and what `git://` URL it will
+appear at.  You can then skip to the section
 "<<pushing-changes-to-a-public-repository,Pushing changes to a public
 repository>>", below.
 
@@ -1962,7 +1963,7 @@ $ mv hooks/post-update.sample hooks/post-update
 (For an explanation of the last two lines, see
 linkgit:git-update-server-info[1] and linkgit:githooks[5].)
 
-Advertise the URL of proj.git.  Anybody else should then be able to
+Advertise the URL of `proj.git`.  Anybody else should then be able to
 clone or pull from that URL, for example with a command line like:
 
 -------------------------------------------------
@@ -1985,8 +1986,8 @@ access, which you will need to update the public repository with the
 latest changes created in your private repository.
 
 The simplest way to do this is using linkgit:git-push[1] and ssh; to
-update the remote branch named "master" with the latest state of your
-branch named "master", run
+update the remote branch named `master` with the latest state of your
+branch named `master`, run
 
 -------------------------------------------------
 $ git push ssh://yourserver.com/~you/proj.git master:master
@@ -2002,7 +2003,7 @@ As with `git fetch`, `git push` will complain if this does not result in a
 <<fast-forwards,fast-forward>>; see the following section for details on
 handling this case.
 
-Note that the target of a "push" is normally a
+Note that the target of a `push` is normally a
 <<def_bare_repository,bare>> repository.  You can also push to a
 repository that has a checked-out working tree, but a push to update the
 currently checked-out branch is denied by default to prevent confusion.
@@ -2030,9 +2031,9 @@ which lets you do the same push with just
 $ git push public-repo master
 -------------------------------------------------
 
-See the explanations of the remote.<name>.url, branch.<name>.remote,
-and remote.<name>.push options in linkgit:git-config[1] for
-details.
+See the explanations of the `remote.<name>.url`,
+`branch.<name>.remote`, and `remote.<name>.push` options in
+linkgit:git-config[1] for details.
 
 [[forcing-push]]
 What to do when a push fails
@@ -2167,7 +2168,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see
 
 Now create the branches in which you are going to work; these start out
 at the current tip of origin/master branch, and should be set up (using
-the --track option to linkgit:git-branch[1]) to merge changes in from
+the `--track` option to linkgit:git-branch[1]) to merge changes in from
 Linus by default.
 
 -------------------------------------------------
@@ -2186,7 +2187,7 @@ Important note!  If you have any local changes in these branches, then
 this merge will create a commit object in the history (with no local
 changes Git will simply do a "fast-forward" merge).  Many people dislike
 the "noise" that this creates in the Linux history, so you should avoid
-doing this capriciously in the "release" branch, as these noisy commits
+doing this capriciously in the `release` branch, as these noisy commits
 will become part of the permanent history when you ask Linus to pull
 from the release branch.
 
@@ -2228,7 +2229,7 @@ patches), and create a new branch from a recent stable tag of
 Linus's branch. Picking a stable base for your branch will:
 1) help you: by avoiding inclusion of unrelated and perhaps lightly
 tested changes
-2) help future bug hunters that use "git bisect" to find problems
+2) help future bug hunters that use `git bisect` to find problems
 
 -------------------------------------------------
 $ git checkout -b speed-up-spinlocks v2.6.35
@@ -2253,9 +2254,9 @@ It is unlikely that you would have any conflicts here ... but you might if you
 spent a while on this step and had also pulled new versions from upstream.
 
 Some time later when enough time has passed and testing done, you can pull the
-same branch into the "release" tree ready to go upstream.  This is where you
+same branch into the `release` tree ready to go upstream.  This is where you
 see the value of keeping each patch (or patch series) in its own branch.  It
-means that the patches can be moved into the "release" tree in any order.
+means that the patches can be moved into the `release` tree in any order.
 
 -------------------------------------------------
 $ git checkout release && git pull . speed-up-spinlocks
@@ -2288,7 +2289,7 @@ If it has been merged, then there will be no output.)
 
 Once a patch completes the great cycle (moving from test to release,
 then pulled by Linus, and finally coming back into your local
-"origin/master" branch), the branch for this change is no longer needed.
+`origin/master` branch), the branch for this change is no longer needed.
 You detect this when the output from:
 
 -------------------------------------------------
@@ -2303,8 +2304,8 @@ $ git branch -d branchname
 
 Some changes are so trivial that it is not necessary to create a separate
 branch and then merge into each of the test and release branches.  For
-these changes, just apply directly to the "release" branch, and then
-merge that into the "test" branch.
+these changes, just apply directly to the `release` branch, and then
+merge that into the `test` branch.
 
 After pushing your work to `mytree`, you can use
 linkgit:git-request-pull[1] to prepare a "please pull" request message
@@ -2475,8 +2476,8 @@ you are rewriting history.
 Keeping a patch series up to date using git rebase
 --------------------------------------------------
 
-Suppose that you create a branch "mywork" on a remote-tracking branch
-"origin", and create some commits on top of it:
+Suppose that you create a branch `mywork` on a remote-tracking branch
+`origin`, and create some commits on top of it:
 
 -------------------------------------------------
 $ git checkout -b mywork origin
@@ -2488,7 +2489,7 @@ $ git commit
 -------------------------------------------------
 
 You have performed no merges into mywork, so it is just a simple linear
-sequence of patches on top of "origin":
+sequence of patches on top of `origin`:
 
 ................................................
  o--o--O <-- origin
@@ -2497,7 +2498,7 @@ sequence of patches on top of "origin":
 ................................................
 
 Some more interesting work has been done in the upstream project, and
-"origin" has advanced:
+`origin` has advanced:
 
 ................................................
  o--o--O--o--o--o <-- origin
@@ -2505,7 +2506,7 @@ Some more interesting work has been done in the upstream project, and
          a--b--c <-- mywork
 ................................................
 
-At this point, you could use "pull" to merge your changes back in;
+At this point, you could use `pull` to merge your changes back in;
 the result would create a new merge commit, like this:
 
 ................................................
@@ -2524,7 +2525,7 @@ $ git rebase origin
 -------------------------------------------------
 
 This will remove each of your commits from mywork, temporarily saving
-them as patches (in a directory named ".git/rebase-apply"), update mywork to
+them as patches (in a directory named `.git/rebase-apply`), update mywork to
 point at the latest version of origin, then apply each of the saved
 patches to the new mywork.  The result will look like:
 
@@ -2795,10 +2796,10 @@ arbitrary name:
 $ git fetch origin todo:my-todo-work
 -------------------------------------------------
 
-The first argument, "origin", just tells Git to fetch from the
+The first argument, `origin`, just tells Git to fetch from the
 repository you originally cloned from.  The second argument tells Git
-to fetch the branch named "todo" from the remote repository, and to
-store it locally under the name refs/heads/my-todo-work.
+to fetch the branch named `todo` from the remote repository, and to
+store it locally under the name `refs/heads/my-todo-work`.
 
 You can also fetch branches from other repositories; so
 
@@ -2806,8 +2807,8 @@ You can also fetch branches from other repositories; so
 $ git fetch git://example.com/proj.git master:example-master
 -------------------------------------------------
 
-will create a new branch named "example-master" and store in it the
-branch named "master" from the repository at the given URL.  If you
+will create a new branch named `example-master` and store in it the
+branch named `master` from the repository at the given URL.  If you
 already have a branch named example-master, it will attempt to
 <<fast-forwards,fast-forward>> to the commit given by example.com's
 master branch.  In more detail:
@@ -2816,7 +2817,7 @@ master branch.  In more detail:
 git fetch and fast-forwards
 ---------------------------
 
-In the previous example, when updating an existing branch, "git fetch"
+In the previous example, when updating an existing branch, `git fetch`
 checks to make sure that the most recent commit on the remote
 branch is a descendant of the most recent commit on your copy of the
 branch before updating your copy of the branch to point at the new
@@ -2842,11 +2843,11 @@ resulting in a situation like:
             o--o--o <-- new head of the branch
 ................................................
 
-In this case, "git fetch" will fail, and print out a warning.
+In this case, `git fetch` will fail, and print out a warning.
 
 In that case, you can still force Git to update to the new head, as
 described in the following section.  However, note that in the
-situation above this may mean losing the commits labeled "a" and "b",
+situation above this may mean losing the commits labeled `a` and `b`,
 unless you've already created a reference of your own pointing to
 them.
 
@@ -2861,7 +2862,7 @@ descendant of the old head, you may force the update with:
 $ git fetch git://example.com/proj.git +master:refs/remotes/example/master
 -------------------------------------------------
 
-Note the addition of the "+" sign.  Alternatively, you can use the "-f"
+Note the addition of the `+` sign.  Alternatively, you can use the `-f`
 flag to force updates of all the fetched branches, as in:
 
 -------------------------------------------------
@@ -2875,7 +2876,7 @@ may be lost, as we saw in the previous section.
 Configuring remote-tracking branches
 ------------------------------------
 
-We saw above that "origin" is just a shortcut to refer to the
+We saw above that `origin` is just a shortcut to refer to the
 repository that you originally cloned from.  This information is
 stored in Git configuration variables, which you can see using
 linkgit:git-config[1]:
@@ -2984,7 +2985,7 @@ Commit Object
 ~~~~~~~~~~~~~
 
 The "commit" object links a physical state of a tree with a description
-of how we got there and why.  Use the --pretty=raw option to
+of how we got there and why.  Use the `--pretty=raw` option to
 linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
 commit:
 
@@ -3026,7 +3027,7 @@ of the tree referred to by this commit with the trees associated with
 its parents.  In particular, Git does not attempt to record file renames
 explicitly, though it can identify cases where the existence of the same
 file data at changing paths suggests a rename.  (See, for example, the
--M option to linkgit:git-diff[1]).
+`-M` option to linkgit:git-diff[1]).
 
 A commit is usually created by linkgit:git-commit[1], which creates a
 commit whose parent is normally the current HEAD, and whose tree is
@@ -3077,7 +3078,7 @@ Blob Object
 ~~~~~~~~~~~
 
 You can use linkgit:git-show[1] to examine the contents of a blob; take,
-for example, the blob in the entry for "COPYING" from the tree above:
+for example, the blob in the entry for `COPYING` from the tree above:
 
 ------------------------------------------------
 $ git show 6ff87c4664
@@ -3160,14 +3161,14 @@ nLE/L9aUXdWeTFPron96DLA=
 See the linkgit:git-tag[1] command to learn how to create and verify tag
 objects.  (Note that linkgit:git-tag[1] can also be used to create
 "lightweight tags", which are not tag objects at all, but just simple
-references whose names begin with "refs/tags/").
+references whose names begin with `refs/tags/`).
 
 [[pack-files]]
 How Git stores objects efficiently: pack files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Newly created objects are initially created in a file named after the
-object's SHA-1 hash (stored in .git/objects).
+object's SHA-1 hash (stored in `.git/objects`).
 
 Unfortunately this system becomes inefficient once a project has a
 lot of objects.  Try this on an old project:
@@ -3208,9 +3209,9 @@ $ git prune
 
 to remove any of the "loose" objects that are now contained in the
 pack.  This will also remove any unreferenced objects (which may be
-created when, for example, you use "git reset" to remove a commit).
+created when, for example, you use `git reset` to remove a commit).
 You can verify that the loose objects are gone by looking at the
-.git/objects directory or by running
+`.git/objects` directory or by running
 
 ------------------------------------------------
 $ git count-objects
@@ -3237,7 +3238,7 @@ branch still exists, as does everything it pointed to. The branch
 pointer itself just doesn't, since you replaced it with another one.
 
 There are also other situations that cause dangling objects. For
-example, a "dangling blob" may arise because you did a "git add" of a
+example, a "dangling blob" may arise because you did a `git add` of a
 file, but then, before you actually committed it and made it part of the
 bigger picture, you changed something else in that file and committed
 that *updated* thing--the old state that you added originally ends up
@@ -3280,14 +3281,14 @@ $ git show <dangling-blob/tree-sha-goes-here>
 ------------------------------------------------
 
 to show what the contents of the blob were (or, for a tree, basically
-what the "ls" for that directory was), and that may give you some idea
+what the `ls` for that directory was), and that may give you some idea
 of what the operation was that left that dangling object.
 
 Usually, dangling blobs and trees aren't very interesting. They're
 almost always the result of either being a half-way mergebase (the blob
 will often even have the conflict markers from a merge in it, if you
 have had conflicting merges that you fixed up by hand), or simply
-because you interrupted a "git fetch" with ^C or something like that,
+because you interrupted a `git fetch` with ^C or something like that,
 leaving _some_ of the new objects in the object database, but just
 dangling and useless.
 
@@ -3298,16 +3299,16 @@ state, you can just prune all unreachable objects:
 $ git prune
 ------------------------------------------------
 
-and they'll be gone. But you should only run "git prune" on a quiescent
+and they'll be gone. But you should only run `git prune` on a quiescent
 repository--it's kind of like doing a filesystem fsck recovery: you
 don't want to do that while the filesystem is mounted.
 
-(The same is true of "git fsck" itself, btw, but since
+(The same is true of `git fsck` itself, btw, but since
 `git fsck` never actually *changes* the repository, it just reports
 on what it found, `git fsck` itself is never 'dangerous' to run.
 Running it while somebody is actually changing the repository can cause
 confusing and scary messages, but it won't actually do anything bad. In
-contrast, running "git prune" while somebody is actively changing the
+contrast, running `git prune` while somebody is actively changing the
 repository is a *BAD* idea).
 
 [[recovering-from-repository-corruption]]
@@ -3345,7 +3346,7 @@ missing blob 4b9458b3786228369c63936db65827de3cc06200
 Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
 points to it.  If you could find just one copy of that missing blob
 object, possibly in some other repository, you could move it into
-.git/objects/4b/9458b3... and be done.  Suppose you can't.  You can
+`.git/objects/4b/9458b3...` and be done.  Suppose you can't.  You can
 still examine the tree that pointed to it with linkgit:git-ls-tree[1],
 which might output something like:
 
@@ -3360,10 +3361,10 @@ $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
 ------------------------------------------------
 
 So now you know that the missing blob was the data for a file named
-"myfile".  And chances are you can also identify the directory--let's
-say it's in "somedirectory".  If you're lucky the missing copy might be
+`myfile`.  And chances are you can also identify the directory--let's
+say it's in `somedirectory`.  If you're lucky the missing copy might be
 the same as the copy you have checked out in your working tree at
-"somedirectory/myfile"; you can test whether that's right with
+`somedirectory/myfile`; you can test whether that's right with
 linkgit:git-hash-object[1]:
 
 ------------------------------------------------
@@ -3418,7 +3419,7 @@ $ git hash-object -w <recreated-file>
 
 and your repository is good again!
 
-(Btw, you could have ignored the fsck, and started with doing a
+(Btw, you could have ignored the `fsck`, and started with doing a
 
 ------------------------------------------------
 $ git log --raw --all
@@ -3432,7 +3433,7 @@ just missing one particular blob version.
 The index
 -----------
 
-The index is a binary file (generally kept in .git/index) containing a
+The index is a binary file (generally kept in `.git/index`) containing a
 sorted list of path names, each with permissions and the SHA-1 of a blob
 object; linkgit:git-ls-files[1] can show you the contents of the index:
 
@@ -3572,7 +3573,7 @@ $ ls -a
 
 The `git submodule add <repo> <path>` command does a couple of things:
 
-- It clones the submodule from <repo> to the given <path> under the
+- It clones the submodule from `<repo>` to the given `<path>` under the
   current directory and by default checks out the master branch.
 - It adds the submodule's clone path to the linkgit:gitmodules[5] file and
   adds this file to the index, ready to be committed.
@@ -3700,11 +3701,11 @@ Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path
 
 In older Git versions it could be easily forgotten to commit new or modified
 files in a submodule, which silently leads to similar problems as not pushing
-the submodule changes. Starting with Git 1.7.0 both "git status" and "git diff"
+the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
 in the superproject show submodules as modified when they contain new or
-modified files to protect against accidentally committing such a state. "git
-diff" will also add a "-dirty" to the work tree side when generating patch
-output or used with the --submodule option:
+modified files to protect against accidentally committing such a state. `git
+diff` will also add a `-dirty` to the work tree side when generating patch
+output or used with the `--submodule` option:
 
 -------------------------------------------------
 $ git diff
@@ -3880,7 +3881,7 @@ or, if you want to check out all of the index, use `-a`.
 
 NOTE! `git checkout-index` normally refuses to overwrite old files, so
 if you have an old version of the tree already checked out, you will
-need to use the "-f" flag ('before' the "-a" flag or the filename) to
+need to use the `-f` flag ('before' the `-a` flag or the filename) to
 'force' the checkout.
 
 
@@ -3891,7 +3892,7 @@ from one representation to the other:
 Tying it all together
 ~~~~~~~~~~~~~~~~~~~~~
 
-To commit a tree you have instantiated with "git write-tree", you'd
+To commit a tree you have instantiated with `git write-tree`, you'd
 create a "commit" object that refers to that tree and the history
 behind it--most notably the "parent" commits that preceded it in
 history.
@@ -4152,8 +4153,9 @@ As a result, the general consistency of an object can always be tested
 independently of the contents or the type of the object: all objects can
 be validated by verifying that (a) their hashes match the content of the
 file and (b) the object successfully inflates to a stream of bytes that
-forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal
-size> {plus} <byte\0> {plus} <binary object data>.
+forms a sequence of
+`<ascii type without space> + <space> + <ascii decimal size> +
+<byte\0> + <binary object data>`.
 
 The structured objects can further have their structure and
 connectivity to other objects verified. This is generally done with
@@ -4632,10 +4634,10 @@ Think about how to create a clear chapter dependency graph that will
 allow people to get to important topics without necessarily reading
 everything in between.
 
-Scan Documentation/ for other stuff left out; in particular:
+Scan `Documentation/` for other stuff left out; in particular:
 
 - howto's
-- some of technical/?
+- some of `technical/`?
 - hooks
 - list of commands in linkgit:git[1]
 
-- 
1.8.2.rc0.16.g20a599e

[PATCH v3 6/9] user-manual: Use 'git config --global user.*' for setup

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

A simple command line call is easier than spawning an editor,
especially for folks new to ideas like the "command line" and "text
editors".  This is also the approach suggested by 'git commit' if you
try and commit without having configured user.name or user.email.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a79b3e31..d9276d7 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -991,9 +991,16 @@ Developing with Git
 Telling Git your name
 ---------------------
 
-Before creating any commits, you should introduce yourself to Git.  The
-easiest way to do so is to make sure the following lines appear in a
-file named `.gitconfig` in your home directory:
+Before creating any commits, you should introduce yourself to Git.
+The easiest way to do so is to use linkgit:git-config[1]:
+
+------------------------------------------------
+$ git config --global user.name 'Your Name Comes Here'
+$ git config --global user.email 'you@yourdomain.example.com'
+------------------------------------------------
+
+Which will adds the following to a file named `.gitconfig` in your
+home directory:
 
 ------------------------------------------------
 [user]
@@ -1001,8 +1008,9 @@ file named `.gitconfig` in your home directory:
 	email = you@yourdomain.example.com
 ------------------------------------------------
 
-(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
-details on the configuration file.)
+See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
+details on the configuration file.  The file is plain text, so you can
+also edit it with your favorite editor.
 
 
 [[creating-a-new-repository]]
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 6/9] user-manual: Use 'git config --global user.*' for setup

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> A simple command line call is easier than spawning an editor,
> especially for folks new to ideas like the "command line" and "text
> editors".  This is also the approach suggested by 'git commit' if you
> try and commit without having configured user.name or user.email.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 18 +++++++++++++-----
>  1 file changed, 13 insertions(+), 5 deletions(-)

This looks like a good 'maint' material that can be applied straight
away there in preparation for 1.8.1.4 to me (modulo typo); reviewers
watching from the sideline, please stop me if you see issues.

>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a79b3e31..d9276d7 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -991,9 +991,16 @@ Developing with Git
>  Telling Git your name
>  ---------------------
>  
> -Before creating any commits, you should introduce yourself to Git.  The
> -easiest way to do so is to make sure the following lines appear in a
> -file named `.gitconfig` in your home directory:
> +Before creating any commits, you should introduce yourself to Git.
> +The easiest way to do so is to use linkgit:git-config[1]:
> +
> +------------------------------------------------
> +$ git config --global user.name 'Your Name Comes Here'
> +$ git config --global user.email 'you@yourdomain.example.com'
> +------------------------------------------------
> +
> +Which will adds the following to a file named `.gitconfig` in your

s/adds/add/;

> +home directory:
>  
>  ------------------------------------------------
>  [user]
> @@ -1001,8 +1008,9 @@ file named `.gitconfig` in your home directory:
>  	email = you@yourdomain.example.com
>  ------------------------------------------------
>  
> -(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
> -details on the configuration file.)
> +See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
> +details on the configuration file.  The file is plain text, so you can
> +also edit it with your favorite editor.
>  
>  
>  [[creating-a-new-repository]]

Re: [PATCH v3 6/9] user-manual: Use 'git config --global user.*' for setup

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 357 bytes --]

On Sun, Feb 17, 2013 at 06:47:09PM -0800, Junio C Hamano wrote:
> > +Which will adds the following to a file named `.gitconfig` in your
> 
> s/adds/add/;

Oops again :p.  This change is SOB me.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v3 7/9] user-manual: Use request-pull to generate "please pull" text

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Less work and more error checking (e.g. does a merge base exist?).
Add an explicit push before request-pull to satisfy request-pull,
which checks to make sure the references are publically available.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d9276d7..cf09ddf 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2304,16 +2304,11 @@ these changes, just apply directly to the `release` branch, and then
 merge that into the `test` branch.
 
 To create diffstat and shortlog summaries of changes to include in a "please
-pull" request to Linus you can use:
+pull" request to Linus you can use linkgit:git-request-pull[1]:
 
 -------------------------------------------------
-$ git diff --stat origin..release
--------------------------------------------------
-
-and
-
--------------------------------------------------
-$ git log -p origin..release | git shortlog
+$ git push mytree
+$ git request-pull origin mytree release
 -------------------------------------------------
 
 Here are some of the scripts that simplify all this even further.
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 7/9] user-manual: Use request-pull to generate "please pull" text

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> Less work and more error checking (e.g. does a merge base exist?).
> Add an explicit push before request-pull to satisfy request-pull,
> which checks to make sure the references are publically available.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 11 +++--------
>  1 file changed, 3 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index d9276d7..cf09ddf 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2304,16 +2304,11 @@ these changes, just apply directly to the `release` branch, and then
>  merge that into the `test` branch.
>  
>  To create diffstat and shortlog summaries of changes to include in a "please
> -pull" request to Linus you can use:
> +pull" request to Linus you can use linkgit:git-request-pull[1]:

The command you refer to does the _whole_ thing, not just to create
diffstat and shortlog summaries to be included.

>  -------------------------------------------------
> +$ git push mytree
> +$ git request-pull origin mytree release
>  -------------------------------------------------

The introductory text to tell the reader what they are being taught
needs to be updated a bit more, I think.

	After pushing your work to "mytree", you can use request-pull
	command to prepare a "please pull" request message to send
	to Linus, like so:

or something.

>  
>  Here are some of the scripts that simplify all this even further.

[PATCH v3 8/9] user-manual: Flesh out uncommitted changes and submodule updates

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

If you try and update a submodule with a dirty working directory, you
get an error message like:

  $ git submodule update
  error: Your local changes to the following files would be overwritten by checkout:
  ...
  Please, commit your changes or stash them before you can switch branches.
  Aborting
  ...

Mention this in the submodule notes.  The previous phrase was short
enough that I originally thought it might have been referring to the
reflog note (obviously, uncommitted changes will not show up in the
reflog either ;).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index cf09ddf..3381c22 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3729,7 +3729,9 @@ module a
 
 NOTE: The changes are still visible in the submodule's reflog.
 
-This is not the case if you did not commit your changes.
+If you did not commit your submodule changes, the changes will *not*
+be silently overwritten.  Instead, you get the usual warning about not
+being able switch from a dirty branch.
 
 [[low-level-operations]]
 Low-level Git operations
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 8/9] user-manual: Flesh out uncommitted changes and submodule updates

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> If you try and update a submodule with a dirty working directory, you
> get an error message like:
>
>   $ git submodule update
>   error: Your local changes to the following files would be overwritten by checkout:
>   ...
>   Please, commit your changes or stash them before you can switch branches.
>   Aborting
>   ...
>
> Mention this in the submodule notes.  The previous phrase was short
> enough that I originally thought it might have been referring to the
> reflog note (obviously, uncommitted changes will not show up in the
> reflog either ;).
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index cf09ddf..3381c22 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -3729,7 +3729,9 @@ module a
>  
>  NOTE: The changes are still visible in the submodule's reflog.
>  
> +If you did not commit your submodule changes, the changes will *not*
> +be silently overwritten.  Instead, you get the usual warning about not
> +being able switch from a dirty branch.

The scenario this talks about is to commit changes in the
superproject and then to run "submodule update".  I think the above
clarification is still incomplete.  You may have committed in the
submodule some changes but not all.

	If you have uncommitted changes in your submodule working
	tree, "git submodule update" will not overwrite them.
	Instead...

would be an improvement, I think.

>  
>  [[low-level-operations]]
>  Low-level Git operations

Re: Re: [PATCH v3 8/9] user-manual: Flesh out uncommitted changes and submodule updates

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 861 bytes --]

On Sun, Feb 17, 2013 at 06:53:59PM -0800, Junio C Hamano wrote:
> > +If you did not commit your submodule changes, the changes will *not*
> > +be silently overwritten.  Instead, you get the usual warning about not
> > +being able switch from a dirty branch.
> 
> The scenario this talks about is to commit changes in the
> superproject and then to run "submodule update".  I think the above
> clarification is still incomplete.  You may have committed in the
> submodule some changes but not all.
> 
> 	If you have uncommitted changes in your submodule working
> 	tree, "git submodule update" will not overwrite them.
> 	Instead...
> 
> would be an improvement, I think.

Will do in v4.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v3 9/9] user-manual: Use -o latest.tar.gz to create a gzipped tarball

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

This functionality was introduced by 0e804e09 (archive: provide
builtin .tar.gz filter, 2011-07-21) for v1.7.7.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 3381c22..af6c09d 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -931,11 +931,20 @@ The linkgit:git-archive[1] command can create a tar or zip archive from
 any version of a project; for example:
 
 -------------------------------------------------
-$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+$ git archive -o latest.tar.gz --prefix=project/ HEAD
 -------------------------------------------------
 
-will use HEAD to produce a tar archive in which each filename is
-preceded by `project/`.
+will use HEAD to produce a gzipped tar archive in which each filename
+is preceded by `project/`.  The output file format is inferred from
+the output file extension if possible, see linkgit:git-archive[1] for
+details.
+
+Versions of Git older than 1.7.7 don't know about the 'tar.gz' format,
+you'll need to use gzip explicitly:
+
+-------------------------------------------------
+$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+-------------------------------------------------
 
 If you're releasing a new version of a software project, you may want
 to simultaneously make a changelog to include in the release
-- 
1.8.1.336.g94702dd

Re: [PATCH v3 9/9] user-manual: Use -o latest.tar.gz to create a gzipped tarball

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> This functionality was introduced by 0e804e09 (archive: provide
> builtin .tar.gz filter, 2011-07-21) for v1.7.7.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---

This looks like a good 'maint' material that can be applied straight
away there if the patch did not depend on 5/9 to cause needless
conflicts.

It is easy for me to deal with conflicts in this particular case,
but in general it would have been more straightforward to manage if
these more localized phrasing fixes came earlier and a larger
file-wide cosmetic change was done after all the others have
settled.

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 3381c22..af6c09d 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -931,11 +931,20 @@ The linkgit:git-archive[1] command can create a tar or zip archive from
>  any version of a project; for example:
>  
>  -------------------------------------------------
> -$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
> +$ git archive -o latest.tar.gz --prefix=project/ HEAD
>  -------------------------------------------------
>  
> -will use HEAD to produce a tar archive in which each filename is
> -preceded by `project/`.
> +will use HEAD to produce a gzipped tar archive in which each filename
> +is preceded by `project/`.  The output file format is inferred from
> +the output file extension if possible, see linkgit:git-archive[1] for
> +details.
> +
> +Versions of Git older than 1.7.7 don't know about the 'tar.gz' format,
> +you'll need to use gzip explicitly:
> +
> +-------------------------------------------------
> +$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
> +-------------------------------------------------
>  
>  If you're releasing a new version of a software project, you may want
>  to simultaneously make a changelog to include in the release

Re: [PATCH v3 9/9] user-manual: Use -o latest.tar.gz to create a gzipped tarball

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 572 bytes --]

On Sun, Feb 17, 2013 at 06:58:58PM -0800, Junio C Hamano wrote:
> It is easy for me to deal with conflicts in this particular case,
> but in general it would have been more straightforward to manage if
> these more localized phrasing fixes came earlier and a larger
> file-wide cosmetic change was done after all the others have
> settled.

Ok.  I'll shift the backtick fix to the back of the stack for v4.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v3 0/9] User manual updates

[Junio C Hamano]

I've taken the following to 'maint', some with minor and obvious
fix-ups:

  user-manual: use 'remote add' to setup push URLs
  user-manual: give 'git push -f' as an alternative to +master
  user-manual: mention 'git remote add' for remote branch config
  user-manual: use 'git config --global user.*' for setup
  user-manual: use -o latest.tar.gz to create a gzipped tarball

I think I've sent reviews for all others, except for the `backtick`
one.  I think it is more efficient to do that one _after_ we are
done with all the others.

Thanks.

Re: [PATCH v3 0/9] User manual updates

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 506 bytes --]

On Mon, Feb 18, 2013 at 12:56:07AM -0800, Junio C Hamano wrote:
> I've taken the following to 'maint'…

Should I rebase v4 onto maint so I don't accidentally collide with any
of the previous patches which have already been merged there?  It
doesn't look like you've pushed the last round of maint additions to
your public repository yet…

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[Drew Northup]

On Thu, Feb 14, 2013 at 1:57 PM, Junio C Hamano <gitster@pobox.com> wrote:

> I did not think the detailed discussion belongs there in the first
> place, so I re-read the context.  I think the only thing the reader
> of the user manual needs to learn at that point of the flow is that
> they can push to a non-bare but cannot push to update the currently
> checked out branch by default.  So let's tone everything down and do
> this instead:

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 85651b5..7c534dc 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1986,9 +1986,10 @@ handling this case.
>
>  Note that the target of a "push" is normally a
>  <<def_bare_repository,bare>> repository.  You can also push to a
> -repository that has a checked-out working tree, but the working tree
> -will not be updated by the push.  This may lead to unexpected results if
> -the branch you push to is the currently checked-out branch!
> +repository that has a checked-out working tree, but a push to update the
> +currently checked-out branch is denied by default to prevent confusion.
> +See the description ofthe receive.denyCurrentBranch option
> +in linkgit:git-config[1] for details.

This looks safe to me, with the minor nit that "ofthe" ("of the")
isn't one word.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse

[Junio C Hamano]

Drew Northup <n1xim.email@gmail.com> writes:

> This looks safe to me, with the minor nit that "ofthe" ("of the")
> isn't one word.

Thanks; typo corrected.

[PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

There is no need to use here documents to setup this configuration.
It is easier, less confusing, and more robust to use Git's
configuration tools directly.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 8524c08..53f73c3 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1994,14 +1994,17 @@ default.  See the description of the receive.denyCurrentBranch option
 in linkgit:git-config[1] for details.
 
 As with `git fetch`, you may also set up configuration options to
-save typing; so, for example, after
+save typing; so, for example, after either
 
--------------------------------------------------
-$ cat >>.git/config <<EOF
-[remote "public-repo"]
-	url = ssh://yourserver.com/~you/proj.git
-EOF
--------------------------------------------------
+------------------------------------------------
+$ git remote add public-repo ssh://yourserver.com/~you/proj.git
+------------------------------------------------
+
+or, more explicitly,
+
+------------------------------------------------
+$ git config remote.public-repo.url ssh://yourserver.com/~you/proj.git
+------------------------------------------------
 
 you should be able to perform the above push with just
 
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> There is no need to use here documents to setup this configuration.
> It is easier, less confusing, and more robust to use Git's
> configuration tools directly.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 17 ++++++++++-------
>  1 file changed, 10 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 8524c08..53f73c3 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1994,14 +1994,17 @@ default.  See the description of the receive.denyCurrentBranch option
>  in linkgit:git-config[1] for details.
>  
>  As with `git fetch`, you may also set up configuration options to
> -save typing; so, for example, after
> +save typing; so, for example, after either
>  
> --------------------------------------------------
> -$ cat >>.git/config <<EOF
> -[remote "public-repo"]
> -	url = ssh://yourserver.com/~you/proj.git
> -EOF
> --------------------------------------------------
> +------------------------------------------------
> +$ git remote add public-repo ssh://yourserver.com/~you/proj.git
> +------------------------------------------------
> +
> +or, more explicitly,
> +
> +------------------------------------------------
> +$ git config remote.public-repo.url ssh://yourserver.com/~you/proj.git
> +------------------------------------------------

Look at how "Fetching branches from other repositories" is done.  It
shows the use of "remote add" and then shows the result by running
"cat" to show the contents.

I think that organization is much nicer than completely hiding how
the result looks like behind another "git config --set" call, like
the latter half of this patch does.  The resulting text may read
like so:

	...
	save typing; so for example:

	------------
        $ git remote add public-repo yourserver.com:proj.git
	------------

	will add this to your configuration:

	------------
        $ cat .git/config
        ...
        [remote "public-repo"]
		url = yourserver.com:proj.git
	...
	------------

	which lets you do the same push with just

	------------
        $ git push public-repo master
	------------

Re: [PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1269 bytes --]

On Sun, Feb 10, 2013 at 01:33:31PM -0800, Junio C Hamano wrote:
> Look at how "Fetching branches from other repositories" is done.  It
> shows the use of "remote add" and then shows the result by running
> "cat" to show the contents.
> 
> I think that organization is much nicer than completely hiding how
> the result looks like behind another "git config --set" call, like
> the latter half of this patch does.

I think for new users, `git config …`'s opacity may a good thing.  Who
cares how Git stores the config values?  Only users who like to edit
the config files by hand (like, um, me ;).  For someone trying to wrap
their head around Git for the first time, the fact that you can read
and set config values which are stored somewhere should be enough.

I don't feel strongly enough in favor of `git config` to push on this
though, so I'd be happy dropping this patch in favor of:

> The resulting text may read like so:
> …

I'm fine with this too, but if this is the suggested route, why bother
with `git config` at all?  Is it just for ease of scripting?

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs

[Jonathan Nieder]

W. Trevor King wrote:
> On Sun, Feb 10, 2013 at 01:33:31PM -0800, Junio C Hamano wrote:

>> The resulting text may read like so:
>> …
>
> I'm fine with this too, but if this is the suggested route, why bother
> with `git config` at all?  Is it just for ease of scripting?

Yes.  It can also be helpful when giving help over IRC, since you
can get reproducible results without assuming the user has a proper
text editor set up, but that is just a special case of scripting. ;-)

For everyday interactive configuration editing, config files have some
good advantages:

 - The settings are easy to read, well organized, and all in one place
 - The file can include comments.

Thanks,
Jonathan

Re: [PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 784 bytes --]

On Sun, Feb 10, 2013 at 02:08:48PM -0800, Jonathan Nieder wrote:
> For everyday interactive configuration editing, config files have some
> good advantages:
> 
>  - The settings are easy to read, well organized, and all in one place
>  - The file can include comments.

I'm convinced, although the settings are in at least three places
(--system, --global, and --local).  Throwing in the XDG stuff stirs up
the file locations, but it's probably safe to assume (at the moment),
that anyone going that route knows what they're doing ;).  If we just
assume `.git/config` and `~/.gitconfig` we should be pretty safe…

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> On Sun, Feb 10, 2013 at 01:33:31PM -0800, Junio C Hamano wrote:
>> Look at how "Fetching branches from other repositories" is done.  It
>> shows the use of "remote add" and then shows the result by running
>> "cat" to show the contents.
>> 
>> I think that organization is much nicer than completely hiding how
>> the result looks like behind another "git config --set" call, like
>> the latter half of this patch does.
>
> I think for new users, `git config …`'s opacity may a good thing

No.  Reducing the fear factor from new users by not hiding simple
things is one of the design of these tutorials, and showing that the
contents of .git/config is a simple, human-readable plain text file
is a part of it.

> I'm fine with this too, but if this is the suggested route, why bother
> with `git config` at all?  Is it just for ease of scripting?

I would actually say why bother with `git remote` at all, when you
can do that with `git config`, but arguably when a Porcelain that is
type-specific exists, use of it would make the life of end users
easier, and that is why we ended up having `git remote add`.  So if
you know how the remote configuration is implemented, you can still
use `config` to do the same, but `remote add` that futzes with many
variables at once would be easier to use for most people.

Re: [PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1692 bytes --]

On Sun, Feb 10, 2013 at 02:45:59PM -0800, Junio C Hamano wrote:
> "W. Trevor King" <wking@tremily.us> writes:
> > I think for new users, `git config …`'s opacity may a good thing
> 
> No.  Reducing the fear factor from new users by not hiding simple
> things is one of the design of these tutorials, and showing that the
> contents of .git/config is a simple, human-readable plain text file
> is a part of it.
> 
> > I'm fine with this too, but if this is the suggested route, why bother
> > with `git config` at all?  Is it just for ease of scripting?
> 
> I would actually say why bother with `git remote` at all, when you
> can do that with `git config`, but arguably when a Porcelain that is
> type-specific exists, use of it would make the life of end users
> easier, and that is why we ended up having `git remote add`.  So if
> you know how the remote configuration is implemented, you can still
> use `config` to do the same, but `remote add` that futzes with many
> variables at once would be easier to use for most people.

Hmm.  It sounds like maybe it would be better to skip both `git
config` and `git remote` and focus on the config file text itself.
Explain what each line does.  When we talk about identifing yourself
(which is, I think, the first point configuration comes up), we can
mention `git config` as an alternative interface.  When we talk about
remotes, we can mention `git remote` as an alternative interface.
Both references would just point you to the man pages.

Thoughts?

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v2 04/15] user-manual: Use git branch --merged

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Use 'git branch --merged origin'.  This feature was introduced by
049716b (branch --merged/--no-merged: allow specifying arbitrary
commit, 2008-07-08), after the documentation that's being replaced
moved into the manual with 9e2163ea (user-manual: move
howto/using-topic-branches into manual, 2007-05-13).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 53f73c3..a8f792d 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2267,10 +2267,10 @@ then pulled by Linus, and finally coming back into your local
 You detect this when the output from:
 
 -------------------------------------------------
-$ git log origin..branchname
+$ git branch --merged origin
 -------------------------------------------------
 
-is empty.  At this point the branch can be deleted:
+lists the branch.  At this point the branch can be deleted:
 
 -------------------------------------------------
 $ git branch -d branchname
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 04/15] user-manual: Use git branch --merged

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> Use 'git branch --merged origin'.  This feature was introduced by
> 049716b (branch --merged/--no-merged: allow specifying arbitrary
> commit, 2008-07-08), after the documentation that's being replaced
> moved into the manual with 9e2163ea (user-manual: move
> howto/using-topic-branches into manual, 2007-05-13).
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 53f73c3..a8f792d 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2267,10 +2267,10 @@ then pulled by Linus, and finally coming back into your local
>  You detect this when the output from:
>  
>  -------------------------------------------------
> -$ git log origin..branchname
> +$ git branch --merged origin
>  -------------------------------------------------
>  
> -is empty.  At this point the branch can be deleted:
> +lists the branch.  At this point the branch can be deleted:

This is making things much less useful.  "branch --merged origin"
will show 47 different branches that you are *not* interested in the
flow of examples in this part of the tutorial.

Also, log origin..branchname allows you to notice a situation where
some but not all of the branch was merged, too.

Re: [PATCH v2 04/15] user-manual: Use git branch --merged

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 586 bytes --]

On Sun, Feb 10, 2013 at 01:37:01PM -0800, Junio C Hamano wrote:
> This is making things much less useful.  "branch --merged origin"
> will show 47 different branches that you are *not* interested in the
> flow of examples in this part of the tutorial.
> 
> Also, log origin..branchname allows you to notice a situation where
> some but not all of the branch was merged, too.

Good points.  I'll drop this patch from v3.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v2 05/15] user-manual: Add a few references to 'git rebase -i'

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I think this interface is much more convenient than extended cherry
picking or using 'git format-patch'.  Inserting a number of references
should raise awareness among new users.  The previously discussed
methods (cherry picking and format-patch-ing) are still useful,
because all of these approaches have the same effect, which may help
demystify the process for newbies.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a8f792d..5d80b40 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2532,6 +2532,13 @@ return mywork to the state it had before you started the rebase:
 $ git rebase --abort
 -------------------------------------------------
 
+If you need to reorder or edit a number of commits in a branch, it may
+be easier to use `git rebase -i`, which allows you to reorder and
+squash commits, as well as marking them for individual editing during
+the rebase.  See linkgit:git-rebase[1] for details, and
+<<reordering-patch-series>> for alternatives.
+
+
 [[rewriting-one-commit]]
 Rewriting a single commit
 -------------------------
@@ -2546,10 +2553,10 @@ $ git commit --amend
 which will replace the old commit by a new commit incorporating your
 changes, giving you a chance to edit the old commit message first.
 
-You can also use a combination of this and linkgit:git-rebase[1] to
-replace a commit further back in your history and recreate the
-intervening changes on top of it.  First, tag the problematic commit
-with
+You can also use a combination of `commit --amend` and
+linkgit:git-rebase[1] (see <<using-git-rebase>>) to replace a commit
+further back in your history and recreate the intervening changes on
+top of it.  First, tag the problematic commit with
 
 -------------------------------------------------
 $ git tag bad mywork~5
@@ -2584,6 +2591,12 @@ new commits having new object names.
 Reordering or selecting from a patch series
 -------------------------------------------
 
+There are a number of ways you can go about editing an existing patch
+series.  The easiest way is probably by using `git rebase -i`,
+mentioned in <<using-git-rebase>>, but whether you use
+linkgit:git-rebase[1] or one of the methods discussed below, the
+effect is the same.  Pick whichever approach you like best.
+
 Given one existing commit, the linkgit:git-cherry-pick[1] command
 allows you to apply the change introduced by that commit and create a
 new commit that records it.  So, for example, if "mywork" points to a
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 05/15] user-manual: Add a few references to 'git rebase -i'

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> I think this interface is much more convenient than extended cherry
> picking or using 'git format-patch'.  Inserting a number of references
> should raise awareness among new users.  The previously discussed
> methods (cherry picking and format-patch-ing) are still useful,
> because all of these approaches have the same effect, which may help
> demystify the process for newbies.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 21 +++++++++++++++++----
>  1 file changed, 17 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a8f792d..5d80b40 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2532,6 +2532,13 @@ return mywork to the state it had before you started the rebase:
>  $ git rebase --abort
>  -------------------------------------------------
>  
> +If you need to reorder or edit a number of commits in a branch, it may
> +be easier to use `git rebase -i`, which allows you to reorder and
> +squash commits, as well as marking them for individual editing during
> +the rebase.  See linkgit:git-rebase[1] for details, and
> +<<reordering-patch-series>> for alternatives.
> +
> +

This change is very good (modulo the extra blank line at the end).

>  [[rewriting-one-commit]]
>  Rewriting a single commit
>  -------------------------
> @@ -2546,10 +2553,10 @@ $ git commit --amend
>  which will replace the old commit by a new commit incorporating your
>  changes, giving you a chance to edit the old commit message first.
>  
> -You can also use a combination of this and linkgit:git-rebase[1] to
> -replace a commit further back in your history and recreate the
> -intervening changes on top of it.  First, tag the problematic commit
> -with
> +You can also use a combination of `commit --amend` and
> +linkgit:git-rebase[1] (see <<using-git-rebase>>) to replace a commit
> +further back in your history and recreate the intervening changes on
> +top of it.  First, tag the problematic commit with

I think this section can use a lot more love.  There is no reason to
have "bad" tag (tagging the tip of mywork might have made sense in
the old days without detached HEAD or reflog), for example.

Alternatively, we can explain only the amending of the tip commit in
this section, removing everything else; I think that is probably a
better option.  The series of sections around here would then look
like:

 * The section before this talked about a straight-forward "rebase";

 * This section then talks about "commit --amend", nothing else;

 * The next section talks about taking "format-patch A..B", flipping
   its output around and applying to A.  Enhance that section with
   the material to be removed from here, which talks about applying
   "format-patch A..B" on top of the amended A.

 * Then add a separate section after that "Reordering or selecting
   from a patch series" section to discuss "rebase -i".

Hmm?

>  -------------------------------------------------
>  $ git tag bad mywork~5
> @@ -2584,6 +2591,12 @@ new commits having new object names.
>  Reordering or selecting from a patch series
>  -------------------------------------------
>  
> +There are a number of ways you can go about editing an existing patch
> +series.  The easiest way is probably by using `git rebase -i`,
> +mentioned in <<using-git-rebase>>, but whether you use
> +linkgit:git-rebase[1] or one of the methods discussed below, the
> +effect is the same.  Pick whichever approach you like best.
> +
>  Given one existing commit, the linkgit:git-cherry-pick[1] command
>  allows you to apply the change introduced by that commit and create a
>  new commit that records it.  So, for example, if "mywork" points to a

Re: [PATCH v2 05/15] user-manual: Add a few references to 'git rebase -i'

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1443 bytes --]

On Sun, Feb 10, 2013 at 01:53:45PM -0800, Junio C Hamano wrote:
> This change is very good (modulo the extra blank line at the end).

Oops.  Will remove from v3.

> Alternatively, we can explain only the amending of the tip commit in
> this section, removing everything else; I think that is probably a
> better option.  The series of sections around here would then look
> like:
> 
>  * The section before this talked about a straight-forward "rebase";
> 
>  * This section then talks about "commit --amend", nothing else;
> 
>  * The next section talks about taking "format-patch A..B", flipping
>    its output around and applying to A.  Enhance that section with
>    the material to be removed from here, which talks about applying
>    "format-patch A..B" on top of the amended A.
> 
>  * Then add a separate section after that "Reordering or selecting
>    from a patch series" section to discuss "rebase -i".
> 
> Hmm?

Works for me.  The 'format-patch' section is also useful, because it's
easy to understand how a mailing list could get inserted between
'format-patch' and 'am' ;).

The problem with a section on 'rebase -i' is that it does such a good
job explaining itself ;).  I suppose I could add a few "screenshots"
:p.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v2 06/15] user-manual: Give 'git push -f' as an alternative to +master

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

This mirrors existing language in the description of 'git fetch'.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5d80b40..a68d6b9 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2045,6 +2045,13 @@ branch name with a plus sign:
 $ git push ssh://yourserver.com/~you/proj.git +master
 -------------------------------------------------
 
+Note the addition of the `+` sign.  Alternatively, you can use the
+`-f` flag to force the remote update, as in:
+
+-------------------------------------------------
+$ git push -f ssh://yourserver.com/~you/proj.git master
+-------------------------------------------------
+
 Normally whenever a branch head in a public repository is modified, it
 is modified to point to a descendant of the commit that it pointed to
 before.  By forcing a push in this situation, you break that convention.
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 06/15] user-manual: Give 'git push -f' as an alternative to +master

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> This mirrors existing language in the description of 'git fetch'.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 5d80b40..a68d6b9 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2045,6 +2045,13 @@ branch name with a plus sign:
>  $ git push ssh://yourserver.com/~you/proj.git +master
>  -------------------------------------------------
>  
> +Note the addition of the `+` sign.  Alternatively, you can use the
> +`-f` flag to force the remote update, as in:
> +
> +-------------------------------------------------
> +$ git push -f ssh://yourserver.com/~you/proj.git master
> +-------------------------------------------------
> +

I didn't check the surrounding examples but would it make it a bit
too advanced to make the example flow push out more than one
branches here (perhaps he is also updating the 'maint' branch)?
Then use of "--force" can be explained as "Instead of adding + to
each and every refs to be pushed, you can use a single -f to force
everything."

The mistake I would want to avoid teaching the readers is to replace

	push $there +master maint

with

	push -f $there master maint

or even worse

	push -f $there
        push -f

Re: [PATCH v2 06/15] user-manual: Give 'git push -f' as an alternative to +master

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1344 bytes --]

On Sun, Feb 10, 2013 at 02:00:50PM -0800, Junio C Hamano wrote:
> "W. Trevor King" <wking@tremily.us> writes:
> > +Note the addition of the `+` sign.  Alternatively, you can use the
> > +`-f` flag to force the remote update, as in:
> > +
> > +-------------------------------------------------
> > +$ git push -f ssh://yourserver.com/~you/proj.git master
> > +-------------------------------------------------
> > +
> 
> I didn't check the surrounding examples but would it make it a bit
> too advanced to make the example flow push out more than one
> branches here (perhaps he is also updating the 'maint' branch)?
> Then use of "--force" can be explained as "Instead of adding + to
> each and every refs to be pushed, you can use a single -f to force
> everything."
> 
> The mistake I would want to avoid teaching the readers is to replace
> 
> 	push $there +master maint
> 
> with
> 
> 	push -f $there master maint
> 
> or even worse
> 
> 	push -f $there
>   push -f

If you feel the need to explain it to the list, we should probably
have an explanatory example in the manual ;).  What about suggesting
`--dry-run` for sanity-checking forced pushes?

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 06/15] user-manual: Give 'git push -f' as an alternative to +master

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> +Note the addition of the `+` sign.  Alternatively, you can use the
>> +`-f` flag to force the remote update, as in:
>> +
>> +-------------------------------------------------
>> +$ git push -f ssh://yourserver.com/~you/proj.git master
>> +-------------------------------------------------
>> +
>
> I didn't check the surrounding examples but would it make it a bit
> too advanced to make the example flow push out more than one
> branches here (perhaps he is also updating the 'maint' branch)?
> Then use of "--force" can be explained as "Instead of adding + to
> each and every refs to be pushed, you can use a single -f to force
> everything."

Now I have.  This is after a "git push" failed, saying that 'master'
does not fast forward, and attempting to push the 'master' out
forcibly.  There is little risk the user would get confused and say
"push -f $there master some-other-branch" in the context of this
flow.

So I think the patch is good, but others may have comments, so I'll
let the patch floating on the list for now.

[PATCH v2 07/15] user-manual: Mention 'git remote add' for remote branch config

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I hardly ever setup remote.<name>.url using 'git config'.  While it
may be instructive to do so, we should also point out 'git remote
add'.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a68d6b9..424cdd6 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2909,8 +2909,23 @@ Also note that all of the above configuration can be performed by
 directly editing the file .git/config instead of using
 linkgit:git-config[1].
 
+You can produce a similar configuration with:
+
+-------------------------------------------------
+$ git remote add example git://example.com/proj.git
+-------------------------------------------------
+
+which adds the following stanza to `.git/config`:
+
+-------------------------------------------------
+[remote "example"]
+        url = git://example.com/proj.git
+        fetch = +refs/heads/*:refs/remotes/example/*
+-------------------------------------------------
+
 See linkgit:git-config[1] for more details on the configuration
-options mentioned above.
+options mentioned above and linkgit:git-fetch[1] for more details on
+the refspec syntax.
 
 
 [[git-concepts]]
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 07/15] user-manual: Mention 'git remote add' for remote branch config

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a68d6b9..424cdd6 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2909,8 +2909,23 @@ Also note that all of the above configuration can be performed by
>  directly editing the file .git/config instead of using
>  linkgit:git-config[1].
>  
> +You can produce a similar configuration with:
> +
> +-------------------------------------------------
> +$ git remote add example git://example.com/proj.git
> +-------------------------------------------------
> +
> +which adds the following stanza to `.git/config`:
> +
> +-------------------------------------------------
> +[remote "example"]
> +        url = git://example.com/proj.git
> +        fetch = +refs/heads/*:refs/remotes/example/*
> +-------------------------------------------------
> +

What the "config remoteexample.fetch" example before this hunk
teaches is stale and is a wrong advice these days.  I suspect that
the original was written very soon after a separate refs/remotes/
hierarchy was introduced, back when it was considered a good and
cautious practice to notice rewinds at the remote by omitting the
"+" from fetch refspecs.  I'd suggest rewriting everything after "If
there are other repositories that you also use frequently,..." of
this section.

Replace the first example after "for example, after" that uses
"config remote.example.url" with the new text in your patch, and
remove everything before "Also note that all of the above
configuration can be performed by directly editing".

Re: [PATCH v2 07/15] user-manual: Mention 'git remote add' for remote branch config

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a68d6b9..424cdd6 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2909,8 +2909,23 @@ Also note that all of the above configuration can be performed by
>  directly editing the file .git/config instead of using
>  linkgit:git-config[1].
>  
> +You can produce a similar configuration with:
> +
> +-------------------------------------------------
> +$ git remote add example git://example.com/proj.git
> +-------------------------------------------------
> +
> +which adds the following stanza to `.git/config`:
> +
> +-------------------------------------------------
> +[remote "example"]
> +        url = git://example.com/proj.git
> +        fetch = +refs/heads/*:refs/remotes/example/*
> +-------------------------------------------------
> +

What the "config remoteexample.fetch" example before this hunk
teaches is stale and is a wrong advice these days.  I suspect that
the original was written very soon after a separate refs/remotes/
hierarchy was introduced, back when it was considered a good and
cautious practice to notice rewinds at the remote by omitting the
"+" from fetch refspecs.  I'd suggest rewriting everything after "If
there are other repositories that you also use frequently,..." of
this section.

Replace the first example after "for example, after" that uses
"config remote.example.url" with the new text in your patch, and
remove everything before "Also note that all of the above
configuration can be performed by directly editing", while keeping
examples of what various forms of "git fetch" would do with the
above configuration file, without mentioning what would happen if
you omitted "+" from them.

Re: [PATCH v2 07/15] user-manual: Mention 'git remote add' for remote branch config

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 531 bytes --]

On Sun, Feb 10, 2013 at 02:09:50PM -0800, Junio C Hamano wrote:
> I'd suggest rewriting everything after "If there are other
> repositories that you also use frequently,..." of this section.
> 
> Replace the first example after "for example, after" that uses
> "config remote.example.url" with the new text in your patch,
> [snip additional advice]

Will do in v3.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v2 08/15] user-manual: Standardize backtick quoting

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I tried to always use backticks for:
* Paths and filenames (e.g. `.git/config`)
* Compound refs (e.g. `origin/HEAD`)
* Git commands (e.g. `git log`)
* Command arguments (e.g. `--pretty`)
* URLs (e.g. `git://`), as a subset of command arguments
* Special characters (e.g. `+` in diffs).
* Config options (e.g. `branch.<name>.remote`)

Branch and tag names are sometimes set off with double quotes,
sometimes set off with backticks, and sometimes left bare.  I tried to
judge when the intention was introducing new terms or conventions
(double quotes), to reference a recently used command argument
(backticks), or to reference the abstract branch/commit (left bare).
Obviously these are not particularly crisp definitions, so my
decisions are fairly arbitrary ;).  When a reference had already been
introduced, I changed further double-quoted instances to backticked
instances.

When new backticks increased the length of a line beyond others in
that block, I re-wrapped blocks to 72 columns.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 300 +++++++++++++++++++++---------------------
 1 file changed, 151 insertions(+), 149 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 424cdd6..8bf37b3 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -19,7 +19,7 @@ Further chapters cover more specialized topics.
 
 Comprehensive reference documentation is available through the man
 pages, or linkgit:git-help[1] command.  For example, for the command
-"git clone <repo>", you can either use:
+`git clone <repo>`, you can either use:
 
 ------------------------------------------------
 $ man git-clone
@@ -66,11 +66,11 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
 The initial clone may be time-consuming for a large project, but you
 will only need to clone once.
 
-The clone command creates a new directory named after the project ("git"
-or "linux-2.6" in the examples above).  After you cd into this
+The clone command creates a new directory named after the project (`git`
+or `linux-2.6` in the examples above).  After you cd into this
 directory, you will see that it contains a copy of the project files,
 called the <<def_working_tree,working tree>>, together with a special
-top-level directory named ".git", which contains all the information
+top-level directory named `.git`, which contains all the information
 about the history of the project.
 
 [[how-to-check-out]]
@@ -188,7 +188,7 @@ As you can see, a commit shows who made the latest change, what they
 did, and why.
 
 Every commit has a 40-hexdigit id, sometimes called the "object name" or the
-"SHA-1 id", shown on the first line of the "git show" output.  You can usually
+"SHA-1 id", shown on the first line of the `git show` output.  You can usually
 refer to a commit by a shorter name, such as a tag or a branch name, but this
 longer name can also be useful.  Most importantly, it is a globally unique
 name for this commit: so if you tell somebody else the object name (for
@@ -268,35 +268,35 @@ Manipulating branches
 Creating, deleting, and modifying branches is quick and easy; here's
 a summary of the commands:
 
-git branch::
+`git branch`::
 	list all branches
-git branch <branch>::
-	create a new branch named <branch>, referencing the same
+`git branch <branch>`::
+	create a new branch named `<branch>`, referencing the same
 	point in history as the current branch
-git branch <branch> <start-point>::
-	create a new branch named <branch>, referencing
-	<start-point>, which may be specified any way you like,
+`git branch <branch> <start-point>`::
+	create a new branch named `<branch>`, referencing
+	`<start-point>`, which may be specified any way you like,
 	including using a branch name or a tag name
-git branch -d <branch>::
-	delete the branch <branch>; if the branch you are deleting
+`git branch -d <branch>`::
+	delete the branch `<branch>`; if the branch you are deleting
 	points to a commit which is not reachable from the current
 	branch, this command will fail with a warning.
-git branch -D <branch>::
+`git branch -D <branch>`::
 	even if the branch points to a commit not reachable
 	from the current branch, you may know that that commit
 	is still reachable from some other branch or tag.  In that
 	case it is safe to use this command to force Git to delete
 	the branch.
-git checkout <branch>::
-	make the current branch <branch>, updating the working
-	directory to reflect the version referenced by <branch>
-git checkout -b <new> <start-point>::
-	create a new branch <new> referencing <start-point>, and
+`git checkout <branch>`::
+	make the current branch `<branch>`, updating the working
+	directory to reflect the version referenced by `<branch>`
+`git checkout -b <new> <start-point>`::
+	create a new branch `<new>` referencing `<start-point>`, and
 	check it out.
 
 The special symbol "HEAD" can always be used to refer to the current
-branch.  In fact, Git uses a file named "HEAD" in the .git directory to
-remember which branch is current:
+branch.  In fact, Git uses a file named `HEAD` in the `.git` directory
+to remember which branch is current:
 
 ------------------------------------------------
 $ cat .git/HEAD
@@ -346,7 +346,7 @@ of the HEAD in the repository that you cloned from.  That repository
 may also have had other branches, though, and your local repository
 keeps branches which track each of those remote branches, called
 remote-tracking branches, which you
-can view using the "-r" option to linkgit:git-branch[1]:
+can view using the `-r` option to linkgit:git-branch[1]:
 
 ------------------------------------------------
 $ git branch -r
@@ -364,7 +364,7 @@ In this example, "origin" is called a remote repository, or "remote"
 for short. The branches of this repository are called "remote
 branches" from our point of view. The remote-tracking branches listed
 above were created based on the remote branches at clone time and will
-be updated by "git fetch" (hence "git pull") and "git push". See
+be updated by `git fetch` (hence `git pull`) and `git push`. See
 <<Updating-a-repository-With-git-fetch>> for details.
 
 You might want to build on one of these remote-tracking branches
@@ -374,7 +374,7 @@ on a branch of your own, just as you would for a tag:
 $ git checkout -b my-todo-copy origin/todo
 ------------------------------------------------
 
-You can also check out "origin/todo" directly to examine it or
+You can also check out `origin/todo` directly to examine it or
 write a one-off patch.  See <<detached-head,detached head>>.
 
 Note that the name "origin" is just the name that Git uses by default
@@ -386,17 +386,17 @@ Naming branches, tags, and other references
 
 Branches, remote-tracking branches, and tags are all references to
 commits.  All references are named with a slash-separated path name
-starting with "refs"; the names we've been using so far are actually
+starting with `refs`; the names we've been using so far are actually
 shorthand:
 
-	- The branch "test" is short for "refs/heads/test".
-	- The tag "v2.6.18" is short for "refs/tags/v2.6.18".
-	- "origin/master" is short for "refs/remotes/origin/master".
+	- The branch `test` is short for `refs/heads/test`.
+	- The tag `v2.6.18` is short for `refs/tags/v2.6.18`.
+	- `origin/master` is short for `refs/remotes/origin/master`.
 
 The full name is occasionally useful if, for example, there ever
 exists a tag and a branch with the same name.
 
-(Newly created refs are actually stored in the .git/refs directory,
+(Newly created refs are actually stored in the `.git/refs` directory,
 under the path given by their name.  However, for efficiency reasons
 they may also be packed together in a single file; see
 linkgit:git-pack-refs[1]).
@@ -418,7 +418,7 @@ Eventually the developer cloned from will do additional work in her
 repository, creating new commits and advancing the branches to point
 at the new commits.
 
-The command "git fetch", with no arguments, will update all of the
+The command `git fetch`, with no arguments, will update all of the
 remote-tracking branches to the latest version found in her
 repository.  It will not touch any of your own branches--not even the
 "master" branch that was created for you on clone.
@@ -438,7 +438,7 @@ $ git fetch linux-nfs
 -------------------------------------------------
 
 New remote-tracking branches will be stored under the shorthand name
-that you gave "git remote add", in this case linux-nfs:
+that you gave `git remote add`, in this case `linux-nfs`:
 
 -------------------------------------------------
 $ git branch -r
@@ -446,10 +446,10 @@ linux-nfs/master
 origin/master
 -------------------------------------------------
 
-If you run "git fetch <remote>" later, the remote-tracking branches for the
-named <remote> will be updated.
+If you run `git fetch <remote>` later, the remote-tracking branches
+for the named `<remote>` will be updated.
 
-If you examine the file .git/config, you will see that Git has added
+If you examine the file `.git/config`, you will see that Git has added
 a new stanza:
 
 -------------------------------------------------
@@ -462,7 +462,7 @@ $ cat .git/config
 -------------------------------------------------
 
 This is what causes Git to track the remote's branches; you may modify
-or delete these configuration options by editing .git/config with a
+or delete these configuration options by editing `.git/config` with a
 text editor.  (See the "CONFIGURATION FILE" section of
 linkgit:git-config[1] for details.)
 
@@ -499,7 +499,7 @@ Bisecting: 3537 revisions left to test after this
 [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
 -------------------------------------------------
 
-If you run "git branch" at this point, you'll see that Git has
+If you run `git branch` at this point, you'll see that Git has
 temporarily moved you in "(no branch)". HEAD is now detached from any
 branch and points directly to a commit (with commit id 65934...) that
 is reachable from "master" but not from v2.6.18. Compile and test it,
@@ -545,11 +545,11 @@ id, and check it out with:
 $ git reset --hard fb47ddb2db...
 -------------------------------------------------
 
-then test, run "bisect good" or "bisect bad" as appropriate, and
+then test, run `bisect good` or `bisect bad` as appropriate, and
 continue.
 
-Instead of "git bisect visualize" and then "git reset --hard
-fb47ddb2db...", you might just want to tell Git that you want to skip
+Instead of `git bisect visualize` and then `git reset --hard
+fb47ddb2db...`, you might just want to tell Git that you want to skip
 the current commit:
 
 -------------------------------------------------
@@ -561,8 +561,8 @@ bad one between some first skipped commits and a later bad commit.
 
 There are also ways to automate the bisecting process if you have a
 test script that can tell a good from a bad commit. See
-linkgit:git-bisect[1] for more information about this and other "git
-bisect" features.
+linkgit:git-bisect[1] for more information about this and other `git
+bisect` features.
 
 [[naming-commits]]
 Naming commits
@@ -591,7 +591,7 @@ $ git show HEAD~4   # the great-great-grandparent
 -------------------------------------------------
 
 Recall that merge commits may have more than one parent; by default,
-^ and ~ follow the first parent listed in the commit, but you can
+`^` and `~` follow the first parent listed in the commit, but you can
 also choose:
 
 -------------------------------------------------
@@ -640,7 +640,7 @@ running
 $ git tag stable-1 1b2e1d63ff
 -------------------------------------------------
 
-You can use stable-1 to refer to the commit 1b2e1d63ff.
+You can use `stable-1` to refer to the commit 1b2e1d63ff.
 
 This creates a "lightweight" tag.  If you would also like to include a
 comment with the tag, and possibly sign it cryptographically, then you
@@ -669,7 +669,7 @@ $ git log -S'foo()'	# commits which add or remove any file data
 -------------------------------------------------
 
 And of course you can combine all of these; the following finds
-commits since v2.5 which touch the Makefile or any file under fs:
+commits since v2.5 which touch the `Makefile` or any file under `fs`:
 
 -------------------------------------------------
 $ git log v2.5.. Makefile fs/
@@ -681,7 +681,7 @@ You can also ask git log to show patches:
 $ git log -p
 -------------------------------------------------
 
-See the "--pretty" option in the linkgit:git-log[1] man page for more
+See the `--pretty` option in the linkgit:git-log[1] man page for more
 display options.
 
 Note that git log starts with the most recent commit and works
@@ -742,8 +742,8 @@ Examples
 Counting the number of commits on a branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Suppose you want to know how many commits you've made on "mybranch"
-since it diverged from "origin":
+Suppose you want to know how many commits you've made on `mybranch`
+since it diverged from `origin`:
 
 -------------------------------------------------
 $ git log --pretty=oneline origin..mybranch | wc -l
@@ -780,7 +780,7 @@ $ git rev-list master
 e05db0fd4f31dde7005f075a84f96b360d05984b
 -------------------------------------------------
 
-Or you could recall that the ... operator selects all commits
+Or you could recall that the `...` operator selects all commits
 contained reachable from either one reference or the other but not
 both: so
 
@@ -880,7 +880,7 @@ Showing commits unique to a given branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Suppose you would like to see all the commits reachable from the branch
-head named "master" but not from any other head in your repository.
+head named `master` but not from any other head in your repository.
 
 We can list all the heads in this repository with
 linkgit:git-show-ref[1]:
@@ -894,7 +894,7 @@ a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
 -------------------------------------------------
 
-We can get just the branch-head names, and remove "master", with
+We can get just the branch-head names, and remove `master`, with
 the help of the standard utilities cut and grep:
 
 -------------------------------------------------
@@ -935,7 +935,7 @@ $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
 -------------------------------------------------
 
 will use HEAD to produce a tar archive in which each filename is
-preceded by "project/".
+preceded by `project/`.
 
 If you're releasing a new version of a software project, you may want
 to simultaneously make a changelog to include in the release
@@ -993,7 +993,7 @@ Telling Git your name
 
 Before creating any commits, you should introduce yourself to Git.  The
 easiest way to do so is to make sure the following lines appear in a
-file named .gitconfig in your home directory:
+file named `.gitconfig` in your home directory:
 
 ------------------------------------------------
 [user]
@@ -1045,7 +1045,7 @@ at step 3, Git maintains a snapshot of the tree's contents in a
 special staging area called "the index."
 
 At the beginning, the content of the index will be identical to
-that of the HEAD.  The command "git diff --cached", which shows
+that of the HEAD.  The command `git diff --cached`, which shows
 the difference between the HEAD and the index, should therefore
 produce no output at that point.
 
@@ -1084,7 +1084,7 @@ $ git diff
 
 shows the difference between the working tree and the index file.
 
-Note that "git add" always adds just the current contents of a file
+Note that `git add` always adds just the current contents of a file
 to the index; further changes to the same file will be ignored unless
 you run `git add` on the file again.
 
@@ -1155,8 +1155,9 @@ annoying to have these untracked files lying around; e.g. they make
 `git add .` practically useless, and they keep showing up in the output of
 `git status`.
 
-You can tell Git to ignore certain files by creating a file called .gitignore
-in the top level of your working directory, with contents such as:
+You can tell Git to ignore certain files by creating a file called
+`.gitignore` in the top level of your working directory, with contents
+such as:
 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.
@@ -1180,10 +1181,10 @@ for other users who clone your repository.
 
 If you wish the exclude patterns to affect only certain repositories
 (instead of every repository for a given project), you may instead put
-them in a file in your repository named .git/info/exclude, or in any file
-specified by the `core.excludesfile` configuration variable.  Some Git
-commands can also take exclude patterns directly on the command line.
-See linkgit:gitignore[5] for the details.
+them in a file in your repository named `.git/info/exclude`, or in any
+file specified by the `core.excludesfile` configuration variable.
+Some Git commands can also take exclude patterns directly on the
+command line.  See linkgit:gitignore[5] for the details.
 
 [[how-to-merge]]
 How to merge
@@ -1196,10 +1197,10 @@ linkgit:git-merge[1]:
 $ git merge branchname
 -------------------------------------------------
 
-merges the development in the branch "branchname" into the current
+merges the development in the branch `branchname` into the current
 branch.
 
-A merge is made by combining the changes made in "branchname" and the
+A merge is made by combining the changes made in `branchname` and the
 changes made up to the latest commit in your current branch since
 their histories forked. The work tree is overwritten by the result of
 the merge when this combining is done cleanly, or overwritten by a
@@ -1321,7 +1322,7 @@ that part is not conflicting and is not shown.  Same for stage 3).
 
 The diff above shows the differences between the working-tree version of
 file.txt and the stage 2 and stage 3 versions.  So instead of preceding
-each line by a single "+" or "-", it now uses two columns: the first
+each line by a single `+` or `-`, it now uses two columns: the first
 column is used for differences between the first parent and the working
 directory copy, and the second for differences between the second parent
 and the working directory copy.  (See the "COMBINED DIFF FORMAT" section
@@ -1596,7 +1597,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
 
 You will see informational messages on dangling objects. They are objects
 that still exist in the repository but are no longer referenced by any of
-your branches, and can (and will) be removed after a while with "gc".
+your branches, and can (and will) be removed after a while with `gc`.
 You can run `git fsck --no-dangling` to suppress these messages, and still
 view real errors.
 
@@ -1608,9 +1609,9 @@ Recovering lost changes
 Reflogs
 ^^^^^^^
 
-Say you modify a branch with +linkgit:git-reset[1] \--hard+, and then
-realize that the branch was the only reference you had to that point in
-history.
+Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
+and then realize that the branch was the only reference you had to
+that point in history.
 
 Fortunately, Git also keeps a log, called a "reflog", of all the
 previous values of each branch.  So in this case you can still find the
@@ -1621,8 +1622,8 @@ $ git log master@{1}
 -------------------------------------------------
 
 This lists the commits reachable from the previous version of the
-"master" branch head.  This syntax can be used with any Git command
-that accepts a commit, not just with git log.  Some other examples:
+`master` branch head.  This syntax can be used with any Git command
+that accepts a commit, not just with `git log`.  Some other examples:
 
 -------------------------------------------------
 $ git show master@{2}		# See where the branch pointed 2,
@@ -1726,8 +1727,8 @@ one step:
 $ git pull origin master
 -------------------------------------------------
 
-In fact, if you have "master" checked out, then this branch has been
-configured by "git clone" to get changes from the HEAD branch of the
+In fact, if you have `master` checked out, then this branch has been
+configured by `git clone` to get changes from the HEAD branch of the
 origin repository.  So often you can
 accomplish the above with just a simple
 
@@ -1742,11 +1743,11 @@ the current branch.
 More generally, a branch that is created from a remote-tracking branch
 will pull
 by default from that branch.  See the descriptions of the
-branch.<name>.remote and branch.<name>.merge options in
+`branch.<name>.remote` and `branch.<name>.merge` options in
 linkgit:git-config[1], and the discussion of the `--track` option in
 linkgit:git-checkout[1], to learn how to control these defaults.
 
-In addition to saving you keystrokes, "git pull" also helps you by
+In addition to saving you keystrokes, `git pull` also helps you by
 producing a default commit message documenting the branch and
 repository that you pulled from.
 
@@ -1754,7 +1755,7 @@ repository that you pulled from.
 <<fast-forwards,fast-forward>>; instead, your branch will just be
 updated to point to the latest commit from the upstream branch.)
 
-The `git pull` command can also be given "." as the "remote" repository,
+The `git pull` command can also be given `.` as the "remote" repository,
 in which case it just merges in a branch from the current repository; so
 the commands
 
@@ -1779,7 +1780,7 @@ $ git format-patch origin
 -------------------------------------------------
 
 will produce a numbered series of files in the current directory, one
-for each patch in the current branch but not in origin/HEAD.
+for each patch in the current branch but not in `origin/HEAD`.
 
 `git format-patch` can include an initial "cover letter". You can insert
 commentary on individual patches after the three dash line which
@@ -1801,7 +1802,7 @@ Importing patches to a project
 Git also provides a tool called linkgit:git-am[1] (am stands for
 "apply mailbox"), for importing such an emailed series of patches.
 Just save all of the patch-containing messages, in order, into a
-single mailbox file, say "patches.mbox", then run
+single mailbox file, say `patches.mbox`, then run
 
 -------------------------------------------------
 $ git am -3 patches.mbox
@@ -1809,7 +1810,7 @@ $ git am -3 patches.mbox
 
 Git will apply each patch in order; if any conflicts are found, it
 will stop, and you can fix the conflicts as described in
-"<<resolving-a-merge,Resolving a merge>>".  (The "-3" option tells
+"<<resolving-a-merge,Resolving a merge>>".  (The `-3` option tells
 Git to perform a merge; if you would prefer it just to abort and
 leave your tree and index untouched, you may omit that option.)
 
@@ -1885,7 +1886,7 @@ We explain how to do this in the following sections.
 Setting up a public repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Assume your personal repository is in the directory ~/proj.  We
+Assume your personal repository is in the directory `~/proj`.  We
 first create a new clone of the repository and tell `git daemon` that it
 is meant to be public:
 
@@ -1895,10 +1896,10 @@ $ touch proj.git/git-daemon-export-ok
 -------------------------------------------------
 
 The resulting directory proj.git contains a "bare" git repository--it is
-just the contents of the ".git" directory, without any files checked out
+just the contents of the `.git` directory, without any files checked out
 around it.
 
-Next, copy proj.git to the server where you plan to host the
+Next, copy `proj.git` to the server where you plan to host the
 public repository.  You can use scp, rsync, or whatever is most
 convenient.
 
@@ -1909,8 +1910,8 @@ Exporting a Git repository via the Git protocol
 This is the preferred method.
 
 If someone else administers the server, they should tell you what
-directory to put the repository in, and what git:// URL it will appear
-at.  You can then skip to the section
+directory to put the repository in, and what `git://` URL it will
+appear at.  You can then skip to the section
 "<<pushing-changes-to-a-public-repository,Pushing changes to a public
 repository>>", below.
 
@@ -1945,7 +1946,7 @@ $ mv hooks/post-update.sample hooks/post-update
 (For an explanation of the last two lines, see
 linkgit:git-update-server-info[1] and linkgit:githooks[5].)
 
-Advertise the URL of proj.git.  Anybody else should then be able to
+Advertise the URL of `proj.git`.  Anybody else should then be able to
 clone or pull from that URL, for example with a command line like:
 
 -------------------------------------------------
@@ -1968,8 +1969,8 @@ access, which you will need to update the public repository with the
 latest changes created in your private repository.
 
 The simplest way to do this is using linkgit:git-push[1] and ssh; to
-update the remote branch named "master" with the latest state of your
-branch named "master", run
+update the remote branch named `master` with the latest state of your
+branch named `master`, run
 
 -------------------------------------------------
 $ git push ssh://yourserver.com/~you/proj.git master:master
@@ -1985,7 +1986,7 @@ As with `git fetch`, `git push` will complain if this does not result in a
 <<fast-forwards,fast-forward>>; see the following section for details on
 handling this case.
 
-Note that the target of a "push" is normally a
+Note that the target of a `push` is normally a
 <<def_bare_repository,bare>> repository.  You can also push to a
 repository that has a checked-out working tree, but the working tree
 will not be updated by the push.  To protect against this, pushes to
@@ -2012,9 +2013,9 @@ you should be able to perform the above push with just
 $ git push public-repo master
 -------------------------------------------------
 
-See the explanations of the remote.<name>.url, branch.<name>.remote,
-and remote.<name>.push options in linkgit:git-config[1] for
-details.
+See the explanations of the `remote.<name>.url`,
+`branch.<name>.remote`, and `remote.<name>.push` options in
+linkgit:git-config[1] for details.
 
 [[forcing-push]]
 What to do when a push fails
@@ -2149,7 +2150,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see
 
 Now create the branches in which you are going to work; these start out
 at the current tip of origin/master branch, and should be set up (using
-the --track option to linkgit:git-branch[1]) to merge changes in from
+the `--track` option to linkgit:git-branch[1]) to merge changes in from
 Linus by default.
 
 -------------------------------------------------
@@ -2168,7 +2169,7 @@ Important note!  If you have any local changes in these branches, then
 this merge will create a commit object in the history (with no local
 changes Git will simply do a "fast-forward" merge).  Many people dislike
 the "noise" that this creates in the Linux history, so you should avoid
-doing this capriciously in the "release" branch, as these noisy commits
+doing this capriciously in the `release` branch, as these noisy commits
 will become part of the permanent history when you ask Linus to pull
 from the release branch.
 
@@ -2210,7 +2211,7 @@ patches), and create a new branch from a recent stable tag of
 Linus's branch. Picking a stable base for your branch will:
 1) help you: by avoiding inclusion of unrelated and perhaps lightly
 tested changes
-2) help future bug hunters that use "git bisect" to find problems
+2) help future bug hunters that use `git bisect` to find problems
 
 -------------------------------------------------
 $ git checkout -b speed-up-spinlocks v2.6.35
@@ -2235,9 +2236,9 @@ It is unlikely that you would have any conflicts here ... but you might if you
 spent a while on this step and had also pulled new versions from upstream.
 
 Some time later when enough time has passed and testing done, you can pull the
-same branch into the "release" tree ready to go upstream.  This is where you
+same branch into the `release` tree ready to go upstream.  This is where you
 see the value of keeping each patch (or patch series) in its own branch.  It
-means that the patches can be moved into the "release" tree in any order.
+means that the patches can be moved into the `release` tree in any order.
 
 -------------------------------------------------
 $ git checkout release && git pull . speed-up-spinlocks
@@ -2270,7 +2271,7 @@ If it has been merged, then there will be no output.)
 
 Once a patch completes the great cycle (moving from test to release,
 then pulled by Linus, and finally coming back into your local
-"origin/master" branch), the branch for this change is no longer needed.
+`origin/master` branch), the branch for this change is no longer needed.
 You detect this when the output from:
 
 -------------------------------------------------
@@ -2285,8 +2286,8 @@ $ git branch -d branchname
 
 Some changes are so trivial that it is not necessary to create a separate
 branch and then merge into each of the test and release branches.  For
-these changes, just apply directly to the "release" branch, and then
-merge that into the "test" branch.
+these changes, just apply directly to the `release` branch, and then
+merge that into the `test` branch.
 
 To create diffstat and shortlog summaries of changes to include in a "please
 pull" request to Linus you can use:
@@ -2461,8 +2462,8 @@ you are rewriting history.
 Keeping a patch series up to date using git rebase
 --------------------------------------------------
 
-Suppose that you create a branch "mywork" on a remote-tracking branch
-"origin", and create some commits on top of it:
+Suppose that you create a branch `mywork` on a remote-tracking branch
+`origin`, and create some commits on top of it:
 
 -------------------------------------------------
 $ git checkout -b mywork origin
@@ -2474,7 +2475,7 @@ $ git commit
 -------------------------------------------------
 
 You have performed no merges into mywork, so it is just a simple linear
-sequence of patches on top of "origin":
+sequence of patches on top of `origin`:
 
 ................................................
  o--o--O <-- origin
@@ -2483,7 +2484,7 @@ sequence of patches on top of "origin":
 ................................................
 
 Some more interesting work has been done in the upstream project, and
-"origin" has advanced:
+`origin` has advanced:
 
 ................................................
  o--o--O--o--o--o <-- origin
@@ -2491,7 +2492,7 @@ Some more interesting work has been done in the upstream project, and
          a--b--c <-- mywork
 ................................................
 
-At this point, you could use "pull" to merge your changes back in;
+At this point, you could use `pull` to merge your changes back in;
 the result would create a new merge commit, like this:
 
 ................................................
@@ -2510,7 +2511,7 @@ $ git rebase origin
 -------------------------------------------------
 
 This will remove each of your commits from mywork, temporarily saving
-them as patches (in a directory named ".git/rebase-apply"), update mywork to
+them as patches (in a directory named `.git/rebase-apply`), update mywork to
 point at the latest version of origin, then apply each of the saved
 patches to the new mywork.  The result will look like:
 
@@ -2606,8 +2607,8 @@ effect is the same.  Pick whichever approach you like best.
 
 Given one existing commit, the linkgit:git-cherry-pick[1] command
 allows you to apply the change introduced by that commit and create a
-new commit that records it.  So, for example, if "mywork" points to a
-series of patches on top of "origin", you might do something like:
+new commit that records it.  So, for example, if `mywork` points to a
+series of patches on top of `origin`, you might do something like:
 
 -------------------------------------------------
 $ git checkout -b mywork-new origin
@@ -2771,10 +2772,10 @@ arbitrary name:
 $ git fetch origin todo:my-todo-work
 -------------------------------------------------
 
-The first argument, "origin", just tells Git to fetch from the
+The first argument, `origin`, just tells Git to fetch from the
 repository you originally cloned from.  The second argument tells Git
-to fetch the branch named "todo" from the remote repository, and to
-store it locally under the name refs/heads/my-todo-work.
+to fetch the branch named `todo` from the remote repository, and to
+store it locally under the name `refs/heads/my-todo-work`.
 
 You can also fetch branches from other repositories; so
 
@@ -2782,8 +2783,8 @@ You can also fetch branches from other repositories; so
 $ git fetch git://example.com/proj.git master:example-master
 -------------------------------------------------
 
-will create a new branch named "example-master" and store in it the
-branch named "master" from the repository at the given URL.  If you
+will create a new branch named `example-master` and store in it the
+branch named `master` from the repository at the given URL.  If you
 already have a branch named example-master, it will attempt to
 <<fast-forwards,fast-forward>> to the commit given by example.com's
 master branch.  In more detail:
@@ -2792,7 +2793,7 @@ master branch.  In more detail:
 git fetch and fast-forwards
 ---------------------------
 
-In the previous example, when updating an existing branch, "git fetch"
+In the previous example, when updating an existing branch, `git fetch`
 checks to make sure that the most recent commit on the remote
 branch is a descendant of the most recent commit on your copy of the
 branch before updating your copy of the branch to point at the new
@@ -2818,11 +2819,11 @@ resulting in a situation like:
             o--o--o <-- new head of the branch
 ................................................
 
-In this case, "git fetch" will fail, and print out a warning.
+In this case, `git fetch` will fail, and print out a warning.
 
 In that case, you can still force Git to update to the new head, as
 described in the following section.  However, note that in the
-situation above this may mean losing the commits labeled "a" and "b",
+situation above this may mean losing the commits labeled `a` and `b`,
 unless you've already created a reference of your own pointing to
 them.
 
@@ -2837,7 +2838,7 @@ descendant of the old head, you may force the update with:
 $ git fetch git://example.com/proj.git +master:refs/remotes/example/master
 -------------------------------------------------
 
-Note the addition of the "+" sign.  Alternatively, you can use the "-f"
+Note the addition of the `+` sign.  Alternatively, you can use the `-f`
 flag to force updates of all the fetched branches, as in:
 
 -------------------------------------------------
@@ -2851,7 +2852,7 @@ may be lost, as we saw in the previous section.
 Configuring remote-tracking branches
 ------------------------------------
 
-We saw above that "origin" is just a shortcut to refer to the
+We saw above that `origin` is just a shortcut to refer to the
 repository that you originally cloned from.  This information is
 stored in Git configuration variables, which you can see using
 linkgit:git-config[1]:
@@ -2896,17 +2897,17 @@ $ git fetch example master:refs/remotes/example/master
 $ git fetch example
 -------------------------------------------------
 
-You can also add a "+" to force the update each time:
+You can also add a `+` to force the update each time:
 
 -------------------------------------------------
 $ git config remote.example.fetch +master:refs/remotes/example/master
 -------------------------------------------------
 
-Don't do this unless you're sure you won't mind "git fetch" possibly
-throwing away commits on 'example/master'.
+Don't do this unless you're sure you won't mind `git fetch` possibly
+throwing away commits on `example/master`.
 
 Also note that all of the above configuration can be performed by
-directly editing the file .git/config instead of using
+directly editing the file `.git/config` instead of using
 linkgit:git-config[1].
 
 You can produce a similar configuration with:
@@ -2989,7 +2990,7 @@ Commit Object
 ~~~~~~~~~~~~~
 
 The "commit" object links a physical state of a tree with a description
-of how we got there and why.  Use the --pretty=raw option to
+of how we got there and why.  Use the `--pretty=raw` option to
 linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
 commit:
 
@@ -3031,7 +3032,7 @@ of the tree referred to by this commit with the trees associated with
 its parents.  In particular, Git does not attempt to record file renames
 explicitly, though it can identify cases where the existence of the same
 file data at changing paths suggests a rename.  (See, for example, the
--M option to linkgit:git-diff[1]).
+`-M` option to linkgit:git-diff[1]).
 
 A commit is usually created by linkgit:git-commit[1], which creates a
 commit whose parent is normally the current HEAD, and whose tree is
@@ -3082,7 +3083,7 @@ Blob Object
 ~~~~~~~~~~~
 
 You can use linkgit:git-show[1] to examine the contents of a blob; take,
-for example, the blob in the entry for "COPYING" from the tree above:
+for example, the blob in the entry for `COPYING` from the tree above:
 
 ------------------------------------------------
 $ git show 6ff87c4664
@@ -3165,14 +3166,14 @@ nLE/L9aUXdWeTFPron96DLA=
 See the linkgit:git-tag[1] command to learn how to create and verify tag
 objects.  (Note that linkgit:git-tag[1] can also be used to create
 "lightweight tags", which are not tag objects at all, but just simple
-references whose names begin with "refs/tags/").
+references whose names begin with `refs/tags/`).
 
 [[pack-files]]
 How Git stores objects efficiently: pack files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Newly created objects are initially created in a file named after the
-object's SHA-1 hash (stored in .git/objects).
+object's SHA-1 hash (stored in `.git/objects`).
 
 Unfortunately this system becomes inefficient once a project has a
 lot of objects.  Try this on an old project:
@@ -3213,9 +3214,9 @@ $ git prune
 
 to remove any of the "loose" objects that are now contained in the
 pack.  This will also remove any unreferenced objects (which may be
-created when, for example, you use "git reset" to remove a commit).
+created when, for example, you use `git reset` to remove a commit).
 You can verify that the loose objects are gone by looking at the
-.git/objects directory or by running
+`.git/objects` directory or by running
 
 ------------------------------------------------
 $ git count-objects
@@ -3242,7 +3243,7 @@ branch still exists, as does everything it pointed to. The branch
 pointer itself just doesn't, since you replaced it with another one.
 
 There are also other situations that cause dangling objects. For
-example, a "dangling blob" may arise because you did a "git add" of a
+example, a "dangling blob" may arise because you did a `git add` of a
 file, but then, before you actually committed it and made it part of the
 bigger picture, you changed something else in that file and committed
 that *updated* thing--the old state that you added originally ends up
@@ -3285,14 +3286,14 @@ $ git show <dangling-blob/tree-sha-goes-here>
 ------------------------------------------------
 
 to show what the contents of the blob were (or, for a tree, basically
-what the "ls" for that directory was), and that may give you some idea
+what the `ls` for that directory was), and that may give you some idea
 of what the operation was that left that dangling object.
 
 Usually, dangling blobs and trees aren't very interesting. They're
 almost always the result of either being a half-way mergebase (the blob
 will often even have the conflict markers from a merge in it, if you
 have had conflicting merges that you fixed up by hand), or simply
-because you interrupted a "git fetch" with ^C or something like that,
+because you interrupted a `git fetch` with ^C or something like that,
 leaving _some_ of the new objects in the object database, but just
 dangling and useless.
 
@@ -3303,16 +3304,16 @@ state, you can just prune all unreachable objects:
 $ git prune
 ------------------------------------------------
 
-and they'll be gone. But you should only run "git prune" on a quiescent
+and they'll be gone. But you should only run `git prune` on a quiescent
 repository--it's kind of like doing a filesystem fsck recovery: you
 don't want to do that while the filesystem is mounted.
 
-(The same is true of "git fsck" itself, btw, but since
+(The same is true of `git fsck` itself, btw, but since
 `git fsck` never actually *changes* the repository, it just reports
 on what it found, `git fsck` itself is never 'dangerous' to run.
 Running it while somebody is actually changing the repository can cause
 confusing and scary messages, but it won't actually do anything bad. In
-contrast, running "git prune" while somebody is actively changing the
+contrast, running `git prune` while somebody is actively changing the
 repository is a *BAD* idea).
 
 [[recovering-from-repository-corruption]]
@@ -3350,7 +3351,7 @@ missing blob 4b9458b3786228369c63936db65827de3cc06200
 Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
 points to it.  If you could find just one copy of that missing blob
 object, possibly in some other repository, you could move it into
-.git/objects/4b/9458b3... and be done.  Suppose you can't.  You can
+`.git/objects/4b/9458b3...` and be done.  Suppose you can't.  You can
 still examine the tree that pointed to it with linkgit:git-ls-tree[1],
 which might output something like:
 
@@ -3365,10 +3366,10 @@ $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
 ------------------------------------------------
 
 So now you know that the missing blob was the data for a file named
-"myfile".  And chances are you can also identify the directory--let's
-say it's in "somedirectory".  If you're lucky the missing copy might be
+`myfile`.  And chances are you can also identify the directory--let's
+say it's in `somedirectory`.  If you're lucky the missing copy might be
 the same as the copy you have checked out in your working tree at
-"somedirectory/myfile"; you can test whether that's right with
+`somedirectory/myfile`; you can test whether that's right with
 linkgit:git-hash-object[1]:
 
 ------------------------------------------------
@@ -3423,7 +3424,7 @@ $ git hash-object -w <recreated-file>
 
 and your repository is good again!
 
-(Btw, you could have ignored the fsck, and started with doing a
+(Btw, you could have ignored the `fsck`, and started with doing a
 
 ------------------------------------------------
 $ git log --raw --all
@@ -3437,7 +3438,7 @@ just missing one particular blob version.
 The index
 -----------
 
-The index is a binary file (generally kept in .git/index) containing a
+The index is a binary file (generally kept in `.git/index`) containing a
 sorted list of path names, each with permissions and the SHA-1 of a blob
 object; linkgit:git-ls-files[1] can show you the contents of the index:
 
@@ -3577,7 +3578,7 @@ $ ls -a
 
 The `git submodule add <repo> <path>` command does a couple of things:
 
-- It clones the submodule from <repo> to the given <path> under the
+- It clones the submodule from `<repo>` to the given `<path>` under the
   current directory and by default checks out the master branch.
 - It adds the submodule's clone path to the linkgit:gitmodules[5] file and
   adds this file to the index, ready to be committed.
@@ -3705,11 +3706,11 @@ Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path
 
 In older Git versions it could be easily forgotten to commit new or modified
 files in a submodule, which silently leads to similar problems as not pushing
-the submodule changes. Starting with Git 1.7.0 both "git status" and "git diff"
+the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
 in the superproject show submodules as modified when they contain new or
-modified files to protect against accidentally committing such a state. "git
-diff" will also add a "-dirty" to the work tree side when generating patch
-output or used with the --submodule option:
+modified files to protect against accidentally committing such a state. `git
+diff` will also add a `-dirty` to the work tree side when generating patch
+output or used with the `--submodule` option:
 
 -------------------------------------------------
 $ git diff
@@ -3883,7 +3884,7 @@ or, if you want to check out all of the index, use `-a`.
 
 NOTE! `git checkout-index` normally refuses to overwrite old files, so
 if you have an old version of the tree already checked out, you will
-need to use the "-f" flag ('before' the "-a" flag or the filename) to
+need to use the `-f` flag ('before' the `-a` flag or the filename) to
 'force' the checkout.
 
 
@@ -3894,7 +3895,7 @@ from one representation to the other:
 Tying it all together
 ~~~~~~~~~~~~~~~~~~~~~
 
-To commit a tree you have instantiated with "git write-tree", you'd
+To commit a tree you have instantiated with `git write-tree`, you'd
 create a "commit" object that refers to that tree and the history
 behind it--most notably the "parent" commits that preceded it in
 history.
@@ -4155,8 +4156,9 @@ As a result, the general consistency of an object can always be tested
 independently of the contents or the type of the object: all objects can
 be validated by verifying that (a) their hashes match the content of the
 file and (b) the object successfully inflates to a stream of bytes that
-forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal
-size> {plus} <byte\0> {plus} <binary object data>.
+forms a sequence of
+`<ascii type without space> {plus} <space> {plus} <ascii decimal size>
+{plus} <byte\0> {plus} <binary object data>`.
 
 The structured objects can further have their structure and
 connectivity to other objects verified. This is generally done with
@@ -4635,10 +4637,10 @@ Think about how to create a clear chapter dependency graph that will
 allow people to get to important topics without necessarily reading
 everything in between.
 
-Scan Documentation/ for other stuff left out; in particular:
+Scan `Documentation/` for other stuff left out; in particular:
 
 - howto's
-- some of technical/?
+- some of `technical/`?
 - hooks
 - list of commands in linkgit:git[1]
 
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 08/15] user-manual: Standardize backtick quoting

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1233 bytes --]

On Sun, Feb 10, 2013 at 10:10:34AM -0500, W. Trevor King wrote:
> @@ -4155,8 +4156,9 @@ As a result, the general consistency of an object can always be tested
>  independently of the contents or the type of the object: all objects can
>  be validated by verifying that (a) their hashes match the content of the
>  file and (b) the object successfully inflates to a stream of bytes that
> -forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal
> -size> {plus} <byte\0> {plus} <binary object data>.
> +forms a sequence of
> +`<ascii type without space> {plus} <space> {plus} <ascii decimal size>
> +{plus} <byte\0> {plus} <binary object data>`.
>  
>  The structured objects can further have their structure and
>  connectivity to other objects verified. This is generally done with

Reading through the user-manual history, it looks like I goofed here.
6cf378f0 (docs: stop using asciidoc no-inline-literal, 2012-04-26)
points out that `{plus}` is no longer interpreted inside backticks.
In v3, I'll use `+` instead of `{plus}`.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v2 09/15] user-manual: Use 'git config --global user.*' for setup

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

A simple command line call is easier than spawning an editor,
especially for folks new to ideas like the "command line" and "text
editors".  This is also the approach suggested by 'git commit' if you
try and commit without having configured user.name or user.email.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 8bf37b3..e2e0c86 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -991,9 +991,16 @@ Developing with Git
 Telling Git your name
 ---------------------
 
-Before creating any commits, you should introduce yourself to Git.  The
-easiest way to do so is to make sure the following lines appear in a
-file named `.gitconfig` in your home directory:
+Before creating any commits, you should introduce yourself to Git.
+The easiest way to do so is to use linkgit:git-config[1]:
+
+------------------------------------------------
+$ git config --global user.name 'Your Name Comes Here'
+$ git config --global user.email 'you@yourdomain.example.com'
+------------------------------------------------
+
+Which will add the following stanza to a file named `.gitconfig` in
+your home directory:
 
 ------------------------------------------------
 [user]
@@ -1001,8 +1008,9 @@ file named `.gitconfig` in your home directory:
 	email = you@yourdomain.example.com
 ------------------------------------------------
 
-(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
-details on the configuration file.)
+See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
+details on the configuration file.  The file is plain text, so you can
+also edit it with your favorite editor.
 
 
 [[creating-a-new-repository]]
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 09/15] user-manual: Use 'git config --global user.*' for setup

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> A simple command line call is easier than spawning an editor,
> especially for folks new to ideas like the "command line" and "text
> editors".  This is also the approach suggested by 'git commit' if you
> try and commit without having configured user.name or user.email.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 18 +++++++++++++-----
>  1 file changed, 13 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 8bf37b3..e2e0c86 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -991,9 +991,16 @@ Developing with Git
>  Telling Git your name
>  ---------------------
>  
> -Before creating any commits, you should introduce yourself to Git.  The
> -easiest way to do so is to make sure the following lines appear in a
> -file named `.gitconfig` in your home directory:
> +Before creating any commits, you should introduce yourself to Git.
> +The easiest way to do so is to use linkgit:git-config[1]:
> +
> +------------------------------------------------
> +$ git config --global user.name 'Your Name Comes Here'
> +$ git config --global user.email 'you@yourdomain.example.com'
> +------------------------------------------------
> +
> +Which will add the following stanza to a file named `.gitconfig` in
> +your home directory:

Looks good, even though I do not think we would want/need to confuse
the readers with an unfamiliar word "stanza".

> @@ -1001,8 +1008,9 @@ file named `.gitconfig` in your home directory:
>  	email = you@yourdomain.example.com
>  ------------------------------------------------
>  
> -(See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
> -details on the configuration file.)
> +See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
> +details on the configuration file.  The file is plain text, so you can
> +also edit it with your favorite editor.
>  
>  
>  [[creating-a-new-repository]]

Re: [PATCH v2 09/15] user-manual: Use 'git config --global user.*' for setup

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 619 bytes --]

On Sun, Feb 10, 2013 at 02:12:05PM -0800, Junio C Hamano wrote:
> > +Which will add the following stanza to a file named `.gitconfig` in
> > +your home directory:
> 
> Looks good, even though I do not think we would want/need to confuse
> the readers with an unfamiliar word "stanza".

Aw.  I suppose "section" is better?  (It's what Python's ConfigParser
uses anyway).  I saw "stanza" in another part of the manual and
thought it was quite poetic ;).

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 09/15] user-manual: Use 'git config --global user.*' for setup

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> On Sun, Feb 10, 2013 at 02:12:05PM -0800, Junio C Hamano wrote:
>> > +Which will add the following stanza to a file named `.gitconfig` in
>> > +your home directory:
>> 
>> Looks good, even though I do not think we would want/need to confuse
>> the readers with an unfamiliar word "stanza".
>
> Aw.  I suppose "section" is better?  (It's what Python's ConfigParser
> uses anyway).  I saw "stanza" in another part of the manual and
> thought it was quite poetic ;).

How about not saying anything and say "adds the following"?

Re: [PATCH v2 09/15] user-manual: Use 'git config --global user.*' for setup

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 303 bytes --]

On Sun, Feb 10, 2013 at 02:48:01PM -0800, Junio C Hamano wrote:
> How about not saying anything and say "adds the following"?

Will do in v3.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v2 10/15] user-manual: Fix 'both: so' -> 'both; so' typo

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

The clause "so `git log ...` will return no commits..." is
independent, not a description of "both", so a semicolon is more
appropriate.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index e2e0c86..07e07c1 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -782,7 +782,7 @@ e05db0fd4f31dde7005f075a84f96b360d05984b
 
 Or you could recall that the `...` operator selects all commits
 contained reachable from either one reference or the other but not
-both: so
+both; so
 
 -------------------------------------------------
 $ git log origin...master
-- 
1.8.1.336.g94702dd

[PATCH v2 11/15] user-manual: Fix 'http' -> 'HTTP' typos

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

HTTP is an acronym which has not (yet) made the transition to word
status (unlike "laser", probably because lasers are inherently cooler
than HTTP ;).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 07e07c1..31054a2 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1938,7 +1938,7 @@ Exporting a Git repository via http
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Git protocol gives better performance and reliability, but on a
-host with a web server set up, http exports may be simpler to set up.
+host with a web server set up, HTTP exports may be simpler to set up.
 
 All you need to do is place the newly created bare Git repository in
 a directory that is exported by the web server, and make some
@@ -1964,7 +1964,7 @@ $ git clone http://yourserver.com/~you/proj.git
 (See also
 link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
 for a slightly more sophisticated setup using WebDAV which also
-allows pushing over http.)
+allows pushing over HTTP.)
 
 [[pushing-changes-to-a-public-repository]]
 Pushing changes to a public repository
-- 
1.8.1.336.g94702dd

[PATCH v2 12/15] user-manual: Use request-pull to generate "please pull" text

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Less work and more error checking (e.g. does a merge base exist?).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 31054a2..6446791 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2298,17 +2298,14 @@ these changes, just apply directly to the `release` branch, and then
 merge that into the `test` branch.
 
 To create diffstat and shortlog summaries of changes to include in a "please
-pull" request to Linus you can use:
+pull" request to Linus you can use linkgit:git-request-pull[1]:
 
 -------------------------------------------------
-$ git diff --stat origin..release
+$ git request-pull origin git://example.com/proj.git release
 -------------------------------------------------
 
-and
-
--------------------------------------------------
-$ git log -p origin..release | git shortlog
--------------------------------------------------
+where the `git://` URL points to your <<public-repositories,public
+repository>>.
 
 Here are some of the scripts that simplify all this even further.
 
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 12/15] user-manual: Use request-pull to generate "please pull" text

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> Less work and more error checking (e.g. does a merge base exist?).
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 11 ++++-------
>  1 file changed, 4 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 31054a2..6446791 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2298,17 +2298,14 @@ these changes, just apply directly to the `release` branch, and then
>  merge that into the `test` branch.
>  
>  To create diffstat and shortlog summaries of changes to include in a "please
> -pull" request to Linus you can use:
> +pull" request to Linus you can use linkgit:git-request-pull[1]:
>  
>  -------------------------------------------------
> -$ git diff --stat origin..release
> +$ git request-pull origin git://example.com/proj.git release
>  -------------------------------------------------
>  
> -and
> -
> --------------------------------------------------
> -$ git log -p origin..release | git shortlog
> --------------------------------------------------
> +where the `git://` URL points to your <<public-repositories,public
> +repository>>.
>  
>  Here are some of the scripts that simplify all this even further.

The request-pull checks a lot more than "does a merge base exist?",
no?  Does the examples in this flow push out what you want to be
pulled _before_ running this step?

Re: [PATCH v2 12/15] user-manual: Use request-pull to generate "please pull" text

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 740 bytes --]

On Sun, Feb 10, 2013 at 02:23:48PM -0800, Junio C Hamano wrote:
> The request-pull checks a lot more than "does a merge base exist?",
> no?

It does, but the man page doesn't list the checks, and I didn't want
to read through the source to find them all ;).  Maybe I should, and
then update the man page :p.

> Does the examples in this flow push out what you want to be
> pulled _before_ running this step?

Err, yes.  And I should have used `mytree` unstead of the explicit
URL.  Maybe I should have an explicit push just before the
`request-pull` for extra clarity.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v2 13/15] user-manual: Fix 'you - Git' -> 'you--Git' typo

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Use an em-dash, not a hyphen, to join these clauses.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 6446791..dbd0143 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3436,7 +3436,7 @@ $ git log --raw --all
 ------------------------------------------------
 
 and just looked for the sha of the missing object (4b9458b..) in that
-whole thing. It's up to you - Git does *have* a lot of information, it is
+whole thing. It's up to you--Git does *have* a lot of information, it is
 just missing one particular blob version.
 
 [[the-index]]
-- 
1.8.1.336.g94702dd

[PATCH v2 14/15] user-manual: Flesh out uncommitted changes and submodule updates

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

If you try and update a submodule with a dirty working directory, you
get an error message like:

  $ git submodule update
  error: Your local changes to the following files would be overwritten by checkout:
  ...
  Please, commit your changes or stash them before you can switch branches.
  Aborting
  ...

Mention this in the submodule notes.  The previous phrase was short
enough that I originally thought it might have been referring to the
reflog note (obviously, uncommitted changes will not show up in the
reflog either ;).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index dbd0143..8024758 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3751,7 +3751,9 @@ module a
 
 NOTE: The changes are still visible in the submodule's reflog.
 
-This is not the case if you did not commit your changes.
+If you did not commit your submodule changes, the changes will *not*
+be silently overwritten.  Instead, you get the usual warning about not
+being able switch from a dirty branch.
 
 [[low-level-operations]]
 Low-level Git operations
-- 
1.8.1.336.g94702dd

[PATCH v2 15/15] user-manual: Use --format=tar.gz to create a gzipped tarball

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

This functionality was introduced by 0e804e09 (archive: provide
builtin .tar.gz filter, 2011-07-21) for v1.7.7.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 8024758..c04ea51 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -931,12 +931,19 @@ The linkgit:git-archive[1] command can create a tar or zip archive from
 any version of a project; for example:
 
 -------------------------------------------------
-$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+$ git archive --format=tar.gz --prefix=project/ HEAD >latest.tar.gz
 -------------------------------------------------
 
 will use HEAD to produce a tar archive in which each filename is
 preceded by `project/`.
 
+Versions of Git older than 1.7.7 don't know about the 'tar.gz' format,
+you'll need to use gzip explicitly:
+
+-------------------------------------------------
+$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+-------------------------------------------------
+
 If you're releasing a new version of a software project, you may want
 to simultaneously make a changelog to include in the release
 announcement.
-- 
1.8.1.336.g94702dd

Re: [PATCH v2 15/15] user-manual: Use --format=tar.gz to create a gzipped tarball

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> This functionality was introduced by 0e804e09 (archive: provide
> builtin .tar.gz filter, 2011-07-21) for v1.7.7.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---

This is a "meh" at least to me.  Unless it uses something like

	git archive -o latest.tar.gz --prefix=project/ HEAD
        
it is not all that interesting.

>  Documentation/user-manual.txt | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 8024758..c04ea51 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -931,12 +931,19 @@ The linkgit:git-archive[1] command can create a tar or zip archive from
>  any version of a project; for example:
>  
>  -------------------------------------------------
> -$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
> +$ git archive --format=tar.gz --prefix=project/ HEAD >latest.tar.gz
>  -------------------------------------------------
>  
>  will use HEAD to produce a tar archive in which each filename is
>  preceded by `project/`.
>  
> +Versions of Git older than 1.7.7 don't know about the 'tar.gz' format,
> +you'll need to use gzip explicitly:
> +
> +-------------------------------------------------
> +$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
> +-------------------------------------------------
> +
>  If you're releasing a new version of a software project, you may want
>  to simultaneously make a changelog to include in the release
>  announcement.

Re: [PATCH v2 15/15] user-manual: Use --format=tar.gz to create a gzipped tarball

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 560 bytes --]

On Sun, Feb 10, 2013 at 02:27:08PM -0800, Junio C Hamano wrote:
> This is a "meh" at least to me.  Unless it uses something like
> 
> 	git archive -o latest.tar.gz --prefix=project/ HEAD
>         
> it is not all that interesting.

Great suggestion.  My original goal was to remove the pipe, but if we
can remove the redirection too, that's one less POSIX-ism for newbies
to wonder about ;).

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 15/15] user-manual: Use --format=tar.gz to create a gzipped tarball

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> On Sun, Feb 10, 2013 at 02:27:08PM -0800, Junio C Hamano wrote:
>> This is a "meh" at least to me.  Unless it uses something like
>> 
>> 	git archive -o latest.tar.gz --prefix=project/ HEAD
>>         
>> it is not all that interesting.
>
> Great suggestion.  My original goal was to remove the pipe, but if we
> can remove the redirection too, that's one less POSIX-ism for newbies
> to wonder about ;).

I was referring to more about the implicit format recognition not
pipe.

Re: [PATCH v2 15/15] user-manual: Use --format=tar.gz to create a gzipped tarball

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1081 bytes --]

On Sun, Feb 10, 2013 at 02:52:23PM -0800, Junio C Hamano wrote:
> "W. Trevor King" <wking@tremily.us> writes:
> > On Sun, Feb 10, 2013 at 02:27:08PM -0800, Junio C Hamano wrote:
> >> This is a "meh" at least to me.  Unless it uses something like
> >> 
> >> 	git archive -o latest.tar.gz --prefix=project/ HEAD
> >>         
> >> it is not all that interesting.
> >
> > Great suggestion.  My original goal was to remove the pipe, but if we
> > can remove the redirection too, that's one less POSIX-ism for newbies
> > to wonder about ;).
> 
> I was referring to more about the implicit format recognition not
> pipe.

I'll mention it when I'm linking them to git-archive(1) ;).  I think
the goal in the manual should be to show people that the functionality
exists and is not scary.  Explaining the actual implementation details
and assorted usage details is best left to command-specific
documentation.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v2 00/15] User manual updates

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> This combines my ealier patches:
>
> * user-manual: Rewrite git-gc section for automatic packing
> * user-manual: Update for receive.denyCurrentBranch=refuse
>
> With a number of additional fixups.  Changes since v1:
>
> * user-manual: Rewrite git-gc section for automatic packing:
>   - Reworded following suggestions from Junio.  This removed the
>     phrase containing the 'comression' typo pointed out by Javier.
> * user-manual: Update for receive.denyCurrentBranch=refuse
>   - No changes.
>
> Most of the patches are well-focused, with the exception of
> "Standardize backtick quoting".  I can break this up into smaller
> chunks (e.g. "Standardize backtick quoting in Chapter 1", "Standardize
> backtick quoting in Chapter 2", …) if this is too much to bite off in
> one patch.
>
> I may add additional patches onto the end of this series as I make new
> fixes and the series cooks on the list.

Thanks.  I queued 01, 10, 11, 13 directly on 'maint'; they looked
not just good to me but I wouldn't expect any objection to them.

Others patches may see comments from reviewers, so I didn't pick
them up even for 'pu'.

Re: [PATCH v2 00/15] User manual updates

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 614 bytes --]

On Sun, Feb 10, 2013 at 02:31:11PM -0800, Junio C Hamano wrote:
> Thanks.  I queued 01, 10, 11, 13 directly on 'maint'; they looked
> not just good to me but I wouldn't expect any objection to them.

Ok, I'll drop them from v3.  I based my changes on `master` to avoid
colliding with 2de9b711 (Documentation: the name of the system is
'Git', not 'git', 2013-01-21), but if you shifted them already I
suppose you've fixed any conflicts ;).

Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v3 0/9] User manual updates

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 974 bytes --]

On Mon, Feb 18, 2013 at 07:27:50AM -0500, W. Trevor King wrote:
> On Mon, Feb 18, 2013 at 12:56:07AM -0800, Junio C Hamano wrote:
> > I've taken the following to 'maint'…
> 
> Should I rebase v4 onto maint so I don't accidentally collide with any
> of the previous patches which have already been merged there?

I tried this, but the backtick patch shouldn't move to maint due to:

On Sun, Feb 10, 2013 at 05:36:32PM -0500, W. Trevor King wrote:
> I based my changes on `master` to avoid colliding with 2de9b711
> (Documentation: the name of the system is 'Git', not 'git',
> 2013-01-21), but if you shifted them already I suppose you've fixed
> any conflicts ;).

I'll drop it for now, and revive it after the next release syncs
master and maint.  I've rebased the remaining patches onto `maint`.

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v4 0/3] User manual updates

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Changes since v3 (v3 numbering):

* 1: user-manual: Use 'remote add' to setup push URLs
  - Dropped (graduated into 'maint', e9b4908)
* 2: user-manual: Reorganize the reroll sections, adding 'git rebase -i'
  - Added some comments giving example uses of 'commit --amend'.  This
    should make the section less lonely.
  - Fix s/preferred/needed/
  - Call interactive rebase commands "instructions" and "steps"
  - Reworded interactive rebase return-to-shell description following
    Junio's suggestions.
* 3: user-manual: Give 'git push -f' as an alternative to +master
  - Dropped (graduated into 'maint', d1471e0)
* 4: user-manual: Mention 'git remote add' for remote branch config
  - Dropped (graduated into 'maint', 47adb8a)
* 5: user-manual: Standardize backtick quoting
  - Temporarily dropped (not rebased onto maint, due to conflicts with
    2de9b71 (Documentation: the name of the system is 'Git', not
    'git', 2013-01-21))
* 6: user-manual: Use 'git config --global user.*' for setup
  - Dropped (graduated into 'maint', 632cc3e)
* 7: user-manual: Use request-pull to generate "please pull" text
  - Reworded request-pull introduction based on Junio's suggestions.
* 8: user-manual: Flesh out uncommitted changes and submodule updates
  - Adopt Junio's “did not commit” → “have uncommitted changes”
    rephrasing.
* 9: user-manual: Use -o latest.tar.gz to create a gzipped tarball
  - Dropped (graduated into 'maint', 7ed1690)

W. Trevor King (3):
  user-manual: Reorganize the reroll sections, adding 'git rebase -i'
  user-manual: Use request-pull to generate "please pull" text
  user-manual: Flesh out uncommitted changes and submodule updates

 Documentation/user-manual.txt | 133 ++++++++++++++++++++++++------------------
 1 file changed, 77 insertions(+), 56 deletions(-)

-- 
1.8.1.336.g94702dd

[PATCH v4 1/3] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

I think this interface is often more convenient than extended cherry
picking or using 'git format-patch'.  In fact, I removed the
cherry-pick section entirely.  The entry-level suggestions for
rerolling are now:

1. git commit --amend
2. git format-patch origin
   git reset --hard origin
   ...edit and reorder patches...
   git am *.patch
3. git rebase -i origin

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 115 +++++++++++++++++++++++++-----------------
 1 file changed, 69 insertions(+), 46 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 52c8523..a4dbd9e 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2556,6 +2556,12 @@ return mywork to the state it had before you started the rebase:
 $ git rebase --abort
 -------------------------------------------------
 
+If you need to reorder or edit a number of commits in a branch, it may
+be easier to use `git rebase -i`, which allows you to reorder and
+squash commits, as well as marking them for individual editing during
+the rebase.  See <<interactive-rebase>> for details, and
+<<reordering-patch-series>> for alternatives.
+
 [[rewriting-one-commit]]
 Rewriting a single commit
 -------------------------
@@ -2569,72 +2575,89 @@ $ git commit --amend
 
 which will replace the old commit by a new commit incorporating your
 changes, giving you a chance to edit the old commit message first.
+This is useful for fixing typos in your last commit, or for adjusting
+the patch contents of a poorly staged commit.
 
-You can also use a combination of this and linkgit:git-rebase[1] to
-replace a commit further back in your history and recreate the
-intervening changes on top of it.  First, tag the problematic commit
-with
-
--------------------------------------------------
-$ git tag bad mywork~5
--------------------------------------------------
+If you need to amend commits from deeper in your history, you should
+use <<interactive-rebase,interactive rebase's `edit` instruction>>.
 
-(Either gitk or `git log` may be useful for finding the commit.)
+[[reordering-patch-series]]
+Reordering or selecting from a patch series
+-------------------------------------------
 
-Then check out that commit, edit it, and rebase the rest of the series
-on top of it (note that we could check out the commit on a temporary
-branch, but instead we're using a <<detached-head,detached head>>):
+Sometimes you want to edit a commit deeper in your history.  One
+approach is to use `git format-patch` to create a series of patches,
+then reset the state to before the patches:
 
 -------------------------------------------------
-$ git checkout bad
-$ # make changes here and update the index
-$ git commit --amend
-$ git rebase --onto HEAD bad mywork
+$ git format-patch origin
+$ git reset --hard origin
 -------------------------------------------------
 
-When you're done, you'll be left with mywork checked out, with the top
-patches on mywork reapplied on top of your modified commit.  You can
-then clean up with
+Then modify, reorder, or eliminate patches as needed before applying
+them again with linkgit:git-am[1]:
 
 -------------------------------------------------
-$ git tag -d bad
+$ git am *.patch
 -------------------------------------------------
 
-Note that the immutable nature of git history means that you haven't really
-"modified" existing commits; instead, you have replaced the old commits with
-new commits having new object names.
+[[interactive-rebase]]
+Using interactive rebases
+-------------------------
 
-[[reordering-patch-series]]
-Reordering or selecting from a patch series
--------------------------------------------
+You can also edit a patch series with an interactive rebase.  This is
+the same as <<reordering-patch-series,reordering a patch series using
+`format-patch`>>, so use whichever interface you like best.
 
-Given one existing commit, the linkgit:git-cherry-pick[1] command
-allows you to apply the change introduced by that commit and create a
-new commit that records it.  So, for example, if "mywork" points to a
-series of patches on top of "origin", you might do something like:
+Rebase your current HEAD on the last commit you want to retain as-is.
+For example, if you want to reorder the last 5 commits, use:
 
 -------------------------------------------------
-$ git checkout -b mywork-new origin
-$ gitk origin..mywork &
+$ git rebase -i HEAD~5
 -------------------------------------------------
 
-and browse through the list of patches in the mywork branch using gitk,
-applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using `git commit --amend`.
-The linkgit:git-gui[1] command may also help as it allows you to
-individually select diff hunks for inclusion in the index (by
-right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
-
-Another technique is to use `git format-patch` to create a series of
-patches, then reset the state to before the patches:
+This will open your editor with a list of steps to be taken to perform
+your rebase.
 
 -------------------------------------------------
-$ git format-patch origin
-$ git reset --hard origin
--------------------------------------------------
+pick deadbee The oneline of this commit
+pick fa1afe1 The oneline of the next commit
+...
 
-Then modify, reorder, or eliminate patches as preferred before applying
-them again with linkgit:git-am[1].
+# Rebase c0ffeee..deadbee onto c0ffeee
+#
+# Commands:
+#  p, pick = use commit
+#  r, reword = use commit, but edit the commit message
+#  e, edit = use commit, but stop for amending
+#  s, squash = use commit, but meld into previous commit
+#  f, fixup = like "squash", but discard this commit's log message
+#  x, exec = run command (the rest of the line) using shell
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+# Note that empty commits are commented out
+-------------------------------------------------
+
+As explained in the comments, you can reorder commits, squash them
+together, edit commit messages, etc. by editing the list.  Once you
+are satisfied, save the list and close your editor, and the rebase
+will begin.
+
+The rebase will stop where `pick` has been replaced with `edit` or
+when a step in the list fails to mechanically resolve conflicts and
+needs your help.  When you are done editing and/or resolving conflicts
+you can continue with `git rebase --continue`.  If you decide that
+things are getting too hairy, you can always bail out with `git rebase
+--abort`.  Even after the rebase is complete, you can still recover
+the original branch by using the <<reflogs,reflog>>.
+
+For a more detailed discussion of the procedure and additional tips,
+see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
 
 [[patch-series-tools]]
 Other tools
-- 
1.8.1.336.g94702dd

Re: [PATCH v4 1/3] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> I think this interface is often more convenient than extended cherry
> picking or using 'git format-patch'.  In fact, I removed the
> cherry-pick section entirely.  The entry-level suggestions for
> rerolling are now:
>
> 1. git commit --amend
> 2. git format-patch origin
>    git reset --hard origin
>    ...edit and reorder patches...
>    git am *.patch
> 3. git rebase -i origin
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---

Thanks.

> +Sometimes you want to edit a commit deeper in your history.  One
> +approach is to use `git format-patch` to create a series of patches,
> +then reset the state to before the patches:
>  
>  -------------------------------------------------
> +$ git format-patch origin
> +$ git reset --hard origin
>  -------------------------------------------------

Technically speaking, this does not "reset to before the patches".
You would need "git reset --hard $(git merge-base origin HEAD)" or
something like that.

I think this is fine as-is in the flow of text, where we haven't
taught the readers the use of merge-base to find the fork point.

Re: [PATCH v4 1/3] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1040 bytes --]

On Tue, Feb 19, 2013 at 10:47:04AM -0800, Junio C Hamano wrote:
> "W. Trevor King" <wking@tremily.us> writes:
> > +Sometimes you want to edit a commit deeper in your history.  One
> > +approach is to use `git format-patch` to create a series of patches,
> > +then reset the state to before the patches:
> >  
> >  -------------------------------------------------
> > +$ git format-patch origin
> > +$ git reset --hard origin
> >  -------------------------------------------------
> 
> Technically speaking, this does not "reset to before the patches".
> You would need "git reset --hard $(git merge-base origin HEAD)" or
> something like that.

They'll be fine if they haven't fetched since they started their
branch ;).

It does look like I've got an extra comma an a missing “and”.  What
about:

  …create series of patches and then reset…

Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH v4 1/3] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> On Tue, Feb 19, 2013 at 10:47:04AM -0800, Junio C Hamano wrote:
>> "W. Trevor King" <wking@tremily.us> writes:
>> > +Sometimes you want to edit a commit deeper in your history.  One
>> > +approach is to use `git format-patch` to create a series of patches,
>> > +then reset the state to before the patches:
>> >  
>> >  -------------------------------------------------
>> > +$ git format-patch origin
>> > +$ git reset --hard origin
>> >  -------------------------------------------------
>> 
>> Technically speaking, this does not "reset to before the patches".
>> You would need "git reset --hard $(git merge-base origin HEAD)" or
>> something like that.
>
> They'll be fine if they haven't fetched since they started their
> branch ;).
>
> It does look like I've got an extra comma an a missing “and”.  What
> about:
>
>   …create series of patches and then reset…

The original doesn't look too odd to me, but I'll amend to what you
just wrote.

Thanks.

[PATCH] user-manual: Fix the interactive rebase example commit range

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

6c26bf4 (user-manual: Reorganize the reroll sections, adding 'git
rebase -i', 2013-02-19) used deadbee as the oldest commit in the pick
list, but as the final commit in the rebased range, due to sloppy
duplication and extension from git-rebase.txt.  This fixes that by
adding a new HEAD commit.

I also reworded the example commit summaries (onelines), because I
think my initial mistake may have been to to misinterpreting "this
commit" as "HEAD" without thinking things through ;).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5f36f81..a839e57 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2617,11 +2617,12 @@ This will open your editor with a list of steps to be taken to perform
 your rebase.
 
 -------------------------------------------------
-pick deadbee The oneline of this commit
-pick fa1afe1 The oneline of the next commit
+pick deadbee The oneline of HEAD~4
+pick fa1afe1 The oneline of HEAD~3
 ...
+pick 1cef15h The oneline of HEAD
 
-# Rebase c0ffeee..deadbee onto c0ffeee
+# Rebase c0ffeee..1cef15h onto c0ffeee
 #
 # Commands:
 #  p, pick = use commit
-- 
1.8.2.rc0.16.g20a599e

Re: [PATCH] user-manual: Fix the interactive rebase example commit range

[Eric Sunshine]

On Sun, Mar 24, 2013 at 8:23 AM, W. Trevor King <wking@tremily.us> wrote:
> 6c26bf4 (user-manual: Reorganize the reroll sections, adding 'git
> rebase -i', 2013-02-19) used deadbee as the oldest commit in the pick
> list, but as the final commit in the rebased range, due to sloppy
> duplication and extension from git-rebase.txt.  This fixes that by
> adding a new HEAD commit.
>
> I also reworded the example commit summaries (onelines), because I
> think my initial mistake may have been to to misinterpreting "this

s/to to/due to/

> commit" as "HEAD" without thinking things through ;).

Re: [PATCH] user-manual: Fix the interactive rebase example commit range

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 328 bytes --]

On Sun, Mar 24, 2013 at 04:00:17PM -0400, Eric Sunshine wrote:
> On Sun, Mar 24, 2013 at 8:23 AM, W. Trevor King <wking@tremily.us> wrote:
> > I also reworded the example commit summaries (onelines), because I
> > think my initial mistake may have been to to misinterpreting "this
> 
> s/to to/due to/

Oops, thanks :).

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[PATCH v4 2/3] user-manual: Use request-pull to generate "please pull" text

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Less work and more error checking (e.g. does a merge base exist?).
Add an explicit push before request-pull to satisfy request-pull,
which checks to make sure the references are publically available.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a4dbd9e..3aab106 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2305,17 +2305,13 @@ branch and then merge into each of the test and release branches.  For
 these changes, just apply directly to the "release" branch, and then
 merge that into the "test" branch.
 
-To create diffstat and shortlog summaries of changes to include in a "please
-pull" request to Linus you can use:
+After pushing your work to `mytree`, you can use
+linkgit:git-request-pull[1] to prepare a "please pull" request message
+to send to Linus:
 
 -------------------------------------------------
-$ git diff --stat origin..release
--------------------------------------------------
-
-and
-
--------------------------------------------------
-$ git log -p origin..release | git shortlog
+$ git push mytree
+$ git request-pull origin mytree release
 -------------------------------------------------
 
 Here are some of the scripts that simplify all this even further.
-- 
1.8.1.336.g94702dd

[PATCH v4 3/3] user-manual: Flesh out uncommitted changes and submodule updates

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

If you try and update a submodule with a dirty working directory, you
get an error message like:

  $ git submodule update
  error: Your local changes to the following files would be overwritten by checkout:
  ...
  Please, commit your changes or stash them before you can switch branches.
  Aborting
  ...

Mention this in the submodule notes.  The previous phrase was short
enough that I originally thought it might have been referring to the
reflog note (obviously, uncommitted changes will not show up in the
reflog either ;).

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 Documentation/user-manual.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 3aab106..df7524a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3739,7 +3739,9 @@ module a
 
 NOTE: The changes are still visible in the submodule's reflog.
 
-This is not the case if you did not commit your changes.
+If you have uncommitted changes in your submodule working tree, `git
+submodule update` will not overwrite them.  Instead, you get the usual
+warning about not being able switch from a dirty branch.
 
 [[low-level-operations]]
 Low-level git operations
-- 
1.8.1.336.g94702dd

Re: [PATCH] user-manual: Rewrite git-gc section for automatic packing

[Javier Tia]

> +information from taking up too much space on disk or in memory.  Some
> +git commands may automatically run linkgit:git-gc[1], so you don't
> +have to worry about running it manually.  However, compressing large
> +repositories may take some time, so you might want to disable
> +automatic comression and run it explicitly when you are not doing
                       ^^^^^^^^

You might want to make a little correction by 'compression'.


Regards,

-- 
Javier