[PATCH 6/6] doc: fix formatting in git-update-ref

[Andreas Heiduk]

Remove the parapgraph numbers from lines explaining the reflog format
and typeset these lines in monospace.

Signed-off-by: Andreas Heiduk 
---
 Documentation/git-update-ref.txt | 8 
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index fda8516677..9671423117 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -129,8 +129,8 @@ a line to the log file "$GIT_DIR/logs/" (dereferencing 
all
 symbolic refs before creating the log name) describing the change
 in ref value.  Log lines are formatted as:
 
-. oldsha1 SP newsha1 SP committer LF
-+
+oldsha1 SP newsha1 SP committer LF
+
 Where "oldsha1" is the 40 character hexadecimal value previously
 stored in , "newsha1" is the 40 character hexadecimal value of
  and "committer" is the committer's name, email address
@@ -138,8 +138,8 @@ and date in the standard Git committer ident format.
 
 Optionally with -m:
 
-. oldsha1 SP newsha1 SP committer TAB message LF
-+
+oldsha1 SP newsha1 SP committer TAB message LF
+
 Where all fields are as described above and "message" is the
 value supplied to the -m option.
 
-- 
2.19.1

[PATCH 5/6] doc: fix indentation of listing blocks in gitweb.conf.txt

[Andreas Heiduk]

'gitweb.conf.txt' uses inconsistent indentation in listing blocks and a mix
of listing blocks and literal paragraphs. Both didn't look pretty in the
rendered HTML page.

Signed-off-by: Andreas Heiduk 
---
 Documentation/gitweb.conf.txt | 25 +++--
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 9c8982ec98..c0a326e388 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -19,10 +19,12 @@ end of a line is ignored.  See *perlsyn*(1) for details.
 
 An example:
 
-# gitweb configuration file for http://git.example.org
-#
-our $projectroot = "/srv/git"; # FHS recommendation
-our $site_name = 'Example.org >> Repos';
+
+# gitweb configuration file for http://git.example.org
+#
+our $projectroot = "/srv/git"; # FHS recommendation
+our $site_name = 'Example.org >> Repos';
+
 
 
 The configuration file is used to override the default settings that
@@ -357,6 +359,7 @@ $home_link_str::
 +
 For example, the following setting produces a breadcrumb trail like
 "home / dev / projects / ..." where "projects" is the home link.
++
 
 our @extra_breadcrumbs = (
   [ 'home' => 'https://www.example.org/' ],
@@ -901,14 +904,16 @@ To enable blame, pickaxe search, and snapshot support 
(allowing "tar.gz" and
 "zip" snapshots), while allowing individual projects to turn them off, put
 the following in your GITWEB_CONFIG file:
 
-   $feature{'blame'}{'default'} = [1];
-   $feature{'blame'}{'override'} = 1;
+
+$feature{'blame'}{'default'} = [1];
+$feature{'blame'}{'override'} = 1;
 
-   $feature{'pickaxe'}{'default'} = [1];
-   $feature{'pickaxe'}{'override'} = 1;
+$feature{'pickaxe'}{'default'} = [1];
+$feature{'pickaxe'}{'override'} = 1;
 
-   $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
-   $feature{'snapshot'}{'override'} = 1;
+$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
+$feature{'snapshot'}{'override'} = 1;
+
 
 If you allow overriding for the snapshot feature, you can specify which
 snapshot formats are globally disabled. You can also add any command-line
-- 
2.19.1

[PATCH 3/6] doc: fix inappropriate monospace formatting

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk 
---
 Documentation/git-upload-pack.txt |  1 +
 Documentation/git.txt | 10 +-
 Documentation/gitattributes.txt   | 30 +++---
 Documentation/gitmodules.txt  | 17 ++---
 Documentation/gitsubmodules.txt   | 14 +-
 5 files changed, 40 insertions(+), 32 deletions(-)

diff --git a/Documentation/git-upload-pack.txt 
b/Documentation/git-upload-pack.txt
index 822ad593af..998f52d3df 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -11,6 +11,7 @@ SYNOPSIS
 [verse]
 'git-upload-pack' [--[no-]strict] [--timeout=] [--stateless-rpc]
  [--advertise-refs] 
+
 DESCRIPTION
 ---
 Invoked by 'git fetch-pack', learns what
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 2ac9b1c7fe..00156d64aa 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -402,11 +402,11 @@ Git so take care if using a foreign front-end.
of Git object directories which can be used to search for Git
objects. New objects will not be written to these directories.
 +
-   Entries that begin with `"` (double-quote) will be interpreted
-   as C-style quoted paths, removing leading and trailing
-   double-quotes and respecting backslash escapes. E.g., the value
-   `"path-with-\"-and-:-in-it":vanilla-path` has two paths:
-   `path-with-"-and-:-in-it` and `vanilla-path`.
+Entries that begin with `"` (double-quote) will be interpreted
+as C-style quoted paths, removing leading and trailing
+double-quotes and respecting backslash escapes. E.g., the value
+`"path-with-\"-and-:-in-it":vanilla-path` has two paths:
+`path-with-"-and-:-in-it` and `vanilla-path`.
 
 `GIT_DIR`::
If the `GIT_DIR` environment variable is set then it
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 92010b062e..b8392fc330 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -303,21 +303,21 @@ number of pitfalls:
   attribute. If you decide to use the `working-tree-encoding` attribute
   in your repository, then it is strongly recommended to ensure that all
   clients working with the repository support it.
-
-  For example, Microsoft Visual Studio resources files (`*.rc`) or
-  PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
-  If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
-  a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
-  stored as UTF-8 internally. A client without `working-tree-encoding`
-  support will checkout `foo.ps1` as UTF-8 encoded file. This will
-  typically cause trouble for the users of this file.
-
-  If a Git client, that does not support the `working-tree-encoding`
-  attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
-  stored "as-is" internally (in this example probably as UTF-16).
-  A client with `working-tree-encoding` support will interpret the
-  internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
-  That operation will fail and cause an error.
++
+For example, Microsoft Visual Studio resources files (`*.rc`) or
+PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
+If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
+a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
+stored as UTF-8 internally. A client without `working-tree-encoding`
+support will checkout `foo.ps1` as UTF-8 encoded file. This will
+typically cause trouble for the users of this file.
++
+If a Git client, that does not support the `working-tree-encoding`
+attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
+stored "as-is" internally (in this example probably as UTF-16).
+A client with `working-tree-encoding` support will interpret the
+internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
+That operation will fail and cause an error.
 
 - Reencoding content to non-UTF encodings can cause errors as the
   conversion might not be UTF-8 round trip safe. If you suspect your
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 4d63def206..312b6f9259 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -67,7 +67,8 @@ submodule..fetchRecurseSubmodules::
 submodule..ignore::
Defines under what circumstances "git status" and the diff family show
a submodule as modified. The following values are supported:
-
++
+--
all;; The submodule will never be considered modified (but will
nonetheless show up in the output of status and commit when it has
been staged).
@@ -84,12 +85,14 @@ submodule..ignore::
differences, and modifications to tracked and untracked files are
shown. This is the default option.
 
-   If this option is also present

[PATCH 4/6] doc: fix descripion for 'git tag --format'

[Andreas Heiduk]

The '--format=' is now listed in the 'OPTIONS' section, not only
the '' string itself. The description moved up a few paragraphs
because '' is not a standalone paramater but a parameter for the
option '--format'.

Signed-off-by: Andreas Heiduk 
---
 Documentation/git-tag.txt | 12 ++--
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 92f9c12b87..f2d644e3af 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -187,6 +187,12 @@ This option is only applicable when listing tags without 
annotation lines.
`--create-reflog`, but currently does not negate the setting of
`core.logAllRefUpdates`.
 
+--format=::
+   A string that interpolates `%(fieldname)` from a tag ref being shown
+   and the object it points at.  The format is the same as
+   that of linkgit:git-for-each-ref[1].  When unspecified,
+   defaults to `%(refname:strip=2)`.
+
 ::
The name of the tag to create, delete, or describe.
The new tag name must pass all checks defined by
@@ -198,12 +204,6 @@ This option is only applicable when listing tags without 
annotation lines.
The object that the new tag will refer to, usually a commit.
Defaults to HEAD.
 
-::
-   A string that interpolates `%(fieldname)` from a tag ref being shown
-   and the object it points at.  The format is the same as
-   that of linkgit:git-for-each-ref[1].  When unspecified,
-   defaults to `%(refname:strip=2)`.
-
 CONFIGURATION
 -
 By default, 'git tag' in sign-with-default mode (-s) will use your
-- 
2.19.1

[PATCH 1/6] doc: clarify boundaries of 'git worktree list --porcelain'

[Andreas Heiduk]

Defined delimiters for 'git worktree list --porcelain' make the format
easier to parse in scripts. For example

sed -n '/^worktree ID$/,/^$/p'

extracts only the information for the worktree 'ID'.

The format did not changed since [1], only the guaranty is added.

[1] bb9c03b82a (worktree: add 'list' command, 2015-10-08)

Signed-off-by: Andreas Heiduk 
---
 Documentation/git-worktree.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index e2ee9fc21b..73520434f6 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -270,8 +270,8 @@ Porcelain Format
 The porcelain format has a line per attribute.  Attributes are listed with a
 label and value separated by a single space.  Boolean attributes (like 'bare'
 and 'detached') are listed as a label only, and are only present if and only
-if the value is true.  An empty line indicates the end of a worktree.  For
-example:
+if the value is true.  The first attribute of a worktree is always `worktree`,
+an empty line indicates the end of the record.  For example:
 
 
 $ git worktree list --porcelain
-- 
2.19.1

[PATCH 0/6] various fixes for docs

[Andreas Heiduk]

A small batch of fixes for the docs. All but the very first fixes
formatting and similar stuff. The first one makes parsing 
'git worktree list' more future-proof.

Andreas Heiduk (6):
  doc: clarify boundaries of 'git worktree list --porcelain'
  doc: fix ASCII art tab spacing
  doc: fix inappropriate monospace formatting
  doc: fix descripion for 'git tag --format'
  doc: fix indentation of listing blocks in gitweb.conf.txt
  doc: fix formatting in git-update-ref

 Documentation/git-bisect-lk2009.txt | 30 ++---
 Documentation/git-checkout.txt  | 14 +++---
 Documentation/git-merge-base.txt|  6 +++---
 Documentation/git-tag.txt   | 12 ++--
 Documentation/git-update-ref.txt|  8 
 Documentation/git-upload-pack.txt   |  1 +
 Documentation/git-worktree.txt  |  4 ++--
 Documentation/git.txt   | 10 +-
 Documentation/gitattributes.txt | 30 ++---
 Documentation/gitmodules.txt| 17 +---
 Documentation/gitsubmodules.txt | 14 +-
 Documentation/gitweb.conf.txt   | 25 ++--
 12 files changed, 92 insertions(+), 79 deletions(-)

-- 
2.19.1

Re: Git svn bug on merging svn branches

[Andreas Heiduk]

Hello,

Am 10.10.2018 um 01:38 schrieb Артем Семенов:
> Hello.
> 
> Git svn bug on merging svn branches:
> 
> Svn repository (branches tag trunk).
> 
> 1. Add a some file by svn tools.
> 2. Create a new branch by svn tools (e.g. br1) .
> 3. Create a new branch by svn tools on branch br1 (e.g. br2).
> 4. Add some changes to file f1 in branch br1. Commit by svn tools.
> 5. Clone repository by git svn.
> 6. Create two local branches – br1_svn (on origin/br1) and br2_svn (on
> origin/br2);
> 7. Checkout to br2_svn. Add some changes (e.g add file f2). Execute git
> add, git commit.
> 8. Execute “git merge br1_svn”.
> 9. Checkout to br1_svn.
> 10. Execute “git svn info” - URL refers to br1. (URL:
> https://127.0.0.1/svn/branchtest/branches/br1)
> 11. Execute “git merge br2_svn”.
> 12. Execute “git svn info” - URL refers to br2. (URL:
> https://127.0.0.1/svn/branchtest/branches/br2)

The "CAVEAT" section in the git-svn manual already contains some text about
your case:

   If you do merge, note the following rule: git svn dcommit will attempt
   to commit on top of the SVN commit named in

   git log --grep=^git-svn-id: --first-parent -1

   You must therefore ensure that the most recent commit of the branch you
   want to dcommit to is the first parent of the merge. Chaos will ensue
   otherwise, especially if the first parent is an older commit on the
   same SVN branch.

The paragraphs before these lines give more reasons to avoid a non-linear
history in SVN branches.

Best regards
Andreas Heiduk

Re: [PATCH/RFC] completion: complete all possible -no-

[Andreas Heiduk]

Am 14.05.2018 um 19:26 schrieb Duy Nguyen:
> On Mon, May 14, 2018 at 7:03 PM, Andreas Heiduk <ashei...@gmail.com> wrote:
>> Am 08.05.2018 um 17:24 schrieb Duy Nguyen:
>>> On Mon, Apr 23, 2018 at 7:36 AM, Eric Sunshine <sunsh...@sunshineco.com> 
>>> wrote:
>>>> I haven't looked at the implementation, so this may be an entirely
>>>> stupid suggestion, but would it be possible to instead render the
>>>> completions as?
>>>>
>>>> % git checkout --
>>>> --[no-]conflict=   --[no-]patch
>>>> --[no-]detach  --[no-]progress
>>>> --[no-]ignore-other-worktrees  --[no-]quiet
>>>> --[no-]ignore-skip-worktree-bits   --[no-]recurse-submodules
>>>> --[no-]merge   --theirs
>>>> --[no-]orphan= --[no-]track
>>>> --ours
>>>>
>>>> This would address the problem of the --no-* options taking double the
>>>> screen space.
>>>
>>> It took me so long to reply partly because I remember seeing some guy
>>> doing clever trick with tab completion that also shows a short help
>>> text in addition to the complete words. I could not find that again
>>> and from my reading (also internet searching) it's probably not
>>> possible to do this without trickery.
>>
>> The fish-shell does something like that.
>>
>> > git status --
>> --branch  (Show the branch and tracking info even in short-format)
>> --help   (Display the manual of a git command)
>> --ignore-submodules (Ignore changes to submodules)
>> --porcelain(Give the output in a stable, easy-to-parse format)
>> --short  (Give the output in the short-format)
>> --untracked-files  (The untracked files handling mode)
>>
>> Another tab will put a selection-cursor on the displayed list - you can
>> navigate that list with Cursor-Up/Cursor-Down, select an entry and that
>> entry will be inserted into the commandline. That selection process
>> would be useless if the options are presented as "--[no-]x" because THAT
>> cannot be inserted into the commandline without manual editing. And
>> that's the point of the fast option selection process.
> 
> Good to know.
> 
> BTW I looked at the git.fish completion script [1] and see that recent
> effort to help automate more in git-completion.bash might help there
> too. I notice a lot of options and help text hard coded there, if
> someone can explain to me how git.fish uses those, maybe I can change
> git to export something suitable for git.fish to use too [2].

I'm no expert, but some additional things required by fish (and I
suppose zsh too) but not by bash:

- grouping of long and short options
- help text
- argument types for options

Help text and long/short option grouping look like this:

> git rebase -
--force-rebase  -f(Force the rebase)
--merge  -m   (Use merging strategies to rebase)

All these infos seem to be available in `struct option` (for C stuff
at least). So I guess It would be easiest for Fish & Co if git just
exports the complete info in some stable format.

> 
> For example with latest git (in 'master') doing this
> 
> ./git add --git-completion-helper
> 
> gives you the list of all options of "git add". Giving the help text
> for each option is definitely possible (I just didn't see any use for
> it until I looked at zsh/fish completion scripts) and maybe more in
> the future.
> 
> [1] 
> https://github.com/fish-shell/fish-shell/blob/master/share/completions/git.fish
> [2] But then if your script has to work with old git versions too then
> this is a moot point.

Well, sooner or later those old git versions might not be supported by
those shells exactly due to the involved maintenance overhead. So
providing some helper is a step in the right direction. Not providing
only fossilizes the current state.

Re: [PATCH/RFC] completion: complete all possible -no-

[Andreas Heiduk]

Am 08.05.2018 um 17:24 schrieb Duy Nguyen:
> On Mon, Apr 23, 2018 at 7:36 AM, Eric Sunshine  
> wrote:
>> I haven't looked at the implementation, so this may be an entirely
>> stupid suggestion, but would it be possible to instead render the
>> completions as?
>>
>> % git checkout --
>> --[no-]conflict=   --[no-]patch
>> --[no-]detach  --[no-]progress
>> --[no-]ignore-other-worktrees  --[no-]quiet
>> --[no-]ignore-skip-worktree-bits   --[no-]recurse-submodules
>> --[no-]merge   --theirs
>> --[no-]orphan= --[no-]track
>> --ours
>>
>> This would address the problem of the --no-* options taking double the
>> screen space.
> 
> It took me so long to reply partly because I remember seeing some guy
> doing clever trick with tab completion that also shows a short help
> text in addition to the complete words. I could not find that again
> and from my reading (also internet searching) it's probably not
> possible to do this without trickery.

The fish-shell does something like that.

> git status --
--branch  (Show the branch and tracking info even in short-format)
--help   (Display the manual of a git command)
--ignore-submodules (Ignore changes to submodules)
--porcelain(Give the output in a stable, easy-to-parse format)
--short  (Give the output in the short-format)
--untracked-files  (The untracked files handling mode)

Another tab will put a selection-cursor on the displayed list - you can
navigate that list with Cursor-Up/Cursor-Down, select an entry and that
entry will be inserted into the commandline. That selection process
would be useless if the options are presented as "--[no-]x" because THAT
cannot be inserted into the commandline without manual editing. And
that's the point of the fast option selection process.

> 
>> It's also more intuitive than that lone and somewhat weird-looking
>> "--no-" suggestion.
> 
> It's not that weird if you think about file path completion, where you
> complete one path component at a time not full path, bash just does
> not show you full paths to everything.
> 
> I'm arguing about this because I want to see your reaction, because
> I'm thinking of doing the very same thing for config completion. Right
> now "git config " gives you two pages of all available config
> variables. I'm thinking that we "git config " just shows the
> groups, e.g.
> 
>> ~/w/git $ git config
> add.  interactive.
> advice.   log.
> alias.mailmap.
> am.   man.
> 
> Only when you do "git config log." that it shows you log.*
> 

[PATCH v3 5/7] git-svn: remove ''--add-author-from' for 'commit-diff'

[Andreas Heiduk]

The subcommand 'commit-diff' does not support the option
'--add-author-from'.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Signed-off-by: Eric Wong <e...@80x24.org>
---
 Documentation/git-svn.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index d59379ee23..e9615951d2 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -707,7 +707,7 @@ creating the branch or tag.
 config key: svn.useLogAuthor
 
 --add-author-from::
-   When committing to svn from Git (as part of 'commit-diff', 'set-tree' 
or 'dcommit'
+   When committing to svn from Git (as part of 'set-tree' or 'dcommit'
operations), if the existing log message doesn't already have a
`From:` or `Signed-off-by:` line, append a `From:` line based on the
Git commit's author string.  If you use this, then `--use-log-author`
-- 
2.16.2

[PATCH v3 3/7] doc: clarify ignore rules for git ls-files

[Andreas Heiduk]

Explain that `git ls-files --ignored` requires at least one
of the `--exclude*` options to do its job.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-ls-files.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3ac3e3a77d..f3474b2ede 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -53,7 +53,8 @@ OPTIONS
Show only ignored files in the output. When showing files in the
index, print only those matched by an exclude pattern. When
showing "other" files, show only those matched by an exclude
-   pattern.
+   pattern. Standard ignore rules are not automatically activated,
+   therefore at least one of the `--exclude*` options is required.
 
 -s::
 --stage::
-- 
2.16.2

[PATCH v3 6/7] doc: add note about shell quoting to revision.txt

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Junio C Hamano <gits...@pobox.com>
---
 Documentation/revisions.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index dfcc49c72c..e760416d07 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -7,6 +7,10 @@ syntax.  Here are various ways to spell object names.  The
 ones listed near the end of this list name trees and
 blobs contained in a commit.
 
+NOTE: This document shows the "raw" syntax as seen by git. The shell
+and other UIs might require additional quoting to protect special
+characters and to avoid word splitting.
+
 '', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e'::
   The full SHA-1 object name (40-byte hexadecimal string), or
   a leading substring that is unique within the repository.
@@ -186,6 +190,8 @@ existing tag object.
   is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a
   literal '!' character, followed by 'foo'. Any other sequence beginning with
   ':/!' is reserved for now.
+  Depending on the given text, the shell's word splitting rules might
+  require additional quoting.
 
 ':', e.g. 'HEAD:README', ':README', 'master:./README'::
   A suffix ':' followed by a path names the blob or tree
-- 
2.16.2

[PATCH v3 4/7] doc: add '-d' and '-o' for 'git push'

[Andreas Heiduk]

Add the missing `-o` shortcut for `--push-option` to the synopsis.
Add the missing `-d` shortcut for `--delete` in the main section.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
---
 Documentation/git-push.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 5b08302fc2..f2bbda6e32 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | 
--dry-run] [--receive-pack=]
   [--repo=] [-f | --force] [-d | --delete] [--prune] [-v | 
--verbose]
-  [-u | --set-upstream] [--push-option=]
+  [-u | --set-upstream] [-o  | --push-option=]
   [--[no-]signed|--signed=(true|false|if-asked)]
   [--force-with-lease[=[:]]]
   [--no-verify] [ [...]]
@@ -123,6 +123,7 @@ already exists on the remote side.
will be tab-separated and sent to stdout instead of stderr.  The full
symbolic names of the refs will be given.
 
+-d::
 --delete::
All listed refs are deleted from the remote repository. This is
the same as prefixing all refs with a colon.
-- 
2.16.2

[PATCH v3 7/7] doc: normalize [--options] to [options] in git-diff

[Andreas Heiduk]

SYNOPSIS and other manuals use [options] but DESCRIPTION
used [--options].

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-diff.txt | 14 +++---
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 6593b58299..7c2c442700 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -21,7 +21,7 @@ Show changes between the working tree and the index or a 
tree, changes
 between the index and a tree, changes between two trees, changes between
 two blob objects, or changes between two files on disk.
 
-'git diff' [--options] [--] [...]::
+'git diff' [options] [--] [...]::
 
This form is to view the changes you made relative to
the index (staging area for the next commit).  In other
@@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.
further add to the index but you still haven't.  You can
stage these changes by using linkgit:git-add[1].
 
-'git diff' [--options] --no-index [--]  ::
+'git diff' [options] --no-index [--]  ::
 
This form is to compare the given two paths on the
filesystem.  You can omit the `--no-index` option when
@@ -38,7 +38,7 @@ two blob objects, or changes between two files on disk.
or when running the command outside a working tree
controlled by Git.
 
-'git diff' [--options] --cached [] [--] [...]::
+'git diff' [options] --cached [] [--] [...]::
 
This form is to view the changes you staged for the next
commit relative to the named .  Typically you
@@ -48,7 +48,7 @@ two blob objects, or changes between two files on disk.
 is not given, it shows all staged changes.
--staged is a synonym of --cached.
 
-'git diff' [--options]  [--] [...]::
+'git diff' [options]  [--] [...]::
 
This form is to view the changes you have in your
working tree relative to the named .  You can
@@ -56,18 +56,18 @@ two blob objects, or changes between two files on disk.
branch name to compare with the tip of a different
branch.
 
-'git diff' [--options]   [--] [...]::
+'git diff' [options]   [--] [...]::
 
This is to view the changes between two arbitrary
.
 
-'git diff' [--options] .. [--] [...]::
+'git diff' [options] .. [--] [...]::
 
This is synonymous to the previous form.  If  on
one side is omitted, it will have the same effect as
using HEAD instead.
 
-'git diff' [--options] \... [--] [...]::
+'git diff' [options] \... [--] [...]::
 
This form is to view the changes on the branch containing
and up to the second , starting at a common ancestor
-- 
2.16.2

[PATCH v3 2/7] doc: align 'diff --no-index' in text and synopsis

[Andreas Heiduk]

Make the two '' parameters in DESCRIPTION mandatory and
move the `--options` part to the same place where the other
variants show them. And finally make `--no-index` in SYNOPSIS
as mandatory as in DESCRIPTION.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
---
 Documentation/git-diff.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index b0c1bb95c8..6593b58299 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 'git diff' [options] --cached [] [--] [...]
 'git diff' [options]   [--] [...]
 'git diff' [options]  
-'git diff' [options] [--no-index] [--]  
+'git diff' [options] --no-index [--]  
 
 DESCRIPTION
 ---
@@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.
further add to the index but you still haven't.  You can
stage these changes by using linkgit:git-add[1].
 
-'git diff' --no-index [--options] [--] [...]::
+'git diff' [--options] --no-index [--]  ::
 
This form is to compare the given two paths on the
filesystem.  You can omit the `--no-index` option when
-- 
2.16.2

[PATCH v3 1/7] doc: improve formatting in githooks.txt

[Andreas Heiduk]

Typeset commands and similar things with as `git foo` instead of
'git foo' or 'git-foo' and add linkgit to the commands which run
the hooks.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
---
 Documentation/githooks.txt | 115 +++--
 1 file changed, 58 insertions(+), 57 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index f877f7b7cd..e3c283a174 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -31,7 +31,7 @@ Hooks can get their arguments via the environment, 
command-line
 arguments, and stdin. See the documentation for each hook below for
 details.
 
-'git init' may copy hooks to the new repository, depending on its
+`git init` may copy hooks to the new repository, depending on its
 configuration. See the "TEMPLATE DIRECTORY" section in
 linkgit:git-init[1] for details. When the rest of this document refers
 to "default hooks" it's talking about the default template shipped
@@ -45,9 +45,9 @@ HOOKS
 applypatch-msg
 ~~
 
-This hook is invoked by 'git am'.  It takes a single
+This hook is invoked by linkgit:git-am[1].  It takes a single
 parameter, the name of the file that holds the proposed commit
-log message.  Exiting with a non-zero status causes 'git am' to abort
+log message.  Exiting with a non-zero status causes `git am` to abort
 before applying the patch.
 
 The hook is allowed to edit the message file in place, and can
@@ -61,7 +61,7 @@ The default 'applypatch-msg' hook, when enabled, runs the
 pre-applypatch
 ~~
 
-This hook is invoked by 'git am'.  It takes no parameter, and is
+This hook is invoked by linkgit:git-am[1].  It takes no parameter, and is
 invoked after the patch is applied, but before a commit is made.
 
 If it exits with non-zero status, then the working tree will not be
@@ -76,33 +76,33 @@ The default 'pre-applypatch' hook, when enabled, runs the
 post-applypatch
 ~~~
 
-This hook is invoked by 'git am'.  It takes no parameter,
+This hook is invoked by linkgit:git-am[1].  It takes no parameter,
 and is invoked after the patch is applied and a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
-the outcome of 'git am'.
+the outcome of `git am`.
 
 pre-commit
 ~~
 
-This hook is invoked by 'git commit', and can be bypassed
+This hook is invoked by linkgit:git-commit[1], and can be bypassed
 with the `--no-verify` option.  It takes no parameters, and is
 invoked before obtaining the proposed commit log message and
 making a commit.  Exiting with a non-zero status from this script
-causes the 'git commit' command to abort before creating a commit.
+causes the `git commit` command to abort before creating a commit.
 
 The default 'pre-commit' hook, when enabled, catches introduction
 of lines with trailing whitespaces and aborts the commit when
 such a line is found.
 
-All the 'git commit' hooks are invoked with the environment
+All the `git commit` hooks are invoked with the environment
 variable `GIT_EDITOR=:` if the command will not bring up an editor
 to modify the commit message.
 
 prepare-commit-msg
 ~~
 
-This hook is invoked by 'git commit' right after preparing the
+This hook is invoked by linkgit:git-commit[1] right after preparing the
 default log message, and before the editor is started.
 
 It takes one to three parameters.  The first is the name of the file
@@ -114,7 +114,7 @@ commit is a merge or a `.git/MERGE_MSG` file exists); 
`squash`
 (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by
 a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given).
 
-If the exit status is non-zero, 'git commit' will abort.
+If the exit status is non-zero, `git commit` will abort.
 
 The purpose of the hook is to edit the message file in place, and
 it is not suppressed by the `--no-verify` option.  A non-zero exit
@@ -127,7 +127,7 @@ help message found in the commented portion of the commit 
template.
 commit-msg
 ~~
 
-This hook is invoked by 'git commit' and 'git merge', and can be
+This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and 
can be
 bypassed with the `--no-verify` option.  It takes a single parameter,
 the name of the file that holds the proposed commit log message.
 Exiting with a non-zero status causes the command to abort.
@@ -143,16 +143,16 @@ The default 'commit-msg' hook, when enabled, detects 
duplicate
 post-commit
 ~~~
 
-This hook is invoked by 'git commit'. It takes no parameters, and is
+This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is
 invoked after a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
-the outcome of 'git commit'.
+the outcome of `git commit`.
 
 pre-rebase
 ~~
 
-This hook is called by 'git rebase' and can be used to prevent a
+This hook

[PATCH v3 0/7] Some doc-fixes

[Andreas Heiduk]

Changes since the last reroll:

- Better commit comment for "doc: align 'diff --no-index' in text and synopsis"
  This includes Martin's `s/with/and/` comment.
- Eric's typo fix in "doc: add note about shell quoting to revision.txt"
- Added new patch for git-diff.txt with s/--options/options/.
  This addresses Eric's and Martin's comments.
  

Andreas Heiduk (7):
  doc: improve formatting in githooks.txt
  doc: align 'diff --no-index' in text and synopsis
  doc: clarify ignore rules for git ls-files
  doc: add '-d' and '-o' for 'git push'
  git-svn: remove ''--add-author-from' for 'commit-diff'
  doc: add note about shell quoting to revision.txt
  doc: normalize [--options] to [options] in git-diff

 Documentation/git-diff.txt |  16 +++---
 Documentation/git-ls-files.txt |   3 +-
 Documentation/git-push.txt |   3 +-
 Documentation/git-svn.txt  |   2 +-
 Documentation/githooks.txt | 115 +
 Documentation/revisions.txt|   6 +++
 6 files changed, 77 insertions(+), 68 deletions(-)

-- 
2.16.2

[PATCH v2 7/6] doc: normalize [--options] to [options] in git-diff

[Andreas Heiduk]

SYNOPSIS and other manuals use [options] but DESCRIPTION
used [--options].

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-diff.txt | 14 +++---
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 6593b58299..7c2c442700 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -21,7 +21,7 @@ Show changes between the working tree and the index or a 
tree, changes
 between the index and a tree, changes between two trees, changes between
 two blob objects, or changes between two files on disk.
 
-'git diff' [--options] [--] [...]::
+'git diff' [options] [--] [...]::
 
This form is to view the changes you made relative to
the index (staging area for the next commit).  In other
@@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.
further add to the index but you still haven't.  You can
stage these changes by using linkgit:git-add[1].
 
-'git diff' [--options] --no-index [--]  ::
+'git diff' [options] --no-index [--]  ::
 
This form is to compare the given two paths on the
filesystem.  You can omit the `--no-index` option when
@@ -38,7 +38,7 @@ two blob objects, or changes between two files on disk.
or when running the command outside a working tree
controlled by Git.
 
-'git diff' [--options] --cached [] [--] [...]::
+'git diff' [options] --cached [] [--] [...]::
 
This form is to view the changes you staged for the next
commit relative to the named .  Typically you
@@ -48,7 +48,7 @@ two blob objects, or changes between two files on disk.
 is not given, it shows all staged changes.
--staged is a synonym of --cached.
 
-'git diff' [--options]  [--] [...]::
+'git diff' [options]  [--] [...]::
 
This form is to view the changes you have in your
working tree relative to the named .  You can
@@ -56,18 +56,18 @@ two blob objects, or changes between two files on disk.
branch name to compare with the tip of a different
branch.
 
-'git diff' [--options]   [--] [...]::
+'git diff' [options]   [--] [...]::
 
This is to view the changes between two arbitrary
.
 
-'git diff' [--options] .. [--] [...]::
+'git diff' [options] .. [--] [...]::
 
This is synonymous to the previous form.  If  on
one side is omitted, it will have the same effect as
using HEAD instead.
 
-'git diff' [--options] \... [--] [...]::
+'git diff' [options] \... [--] [...]::
 
This form is to view the changes on the branch containing
and up to the second , starting at a common ancestor
-- 
2.16.2

Re: [PATCH v2 2/6] doc: align 'diff --no-index' in text with synopsis

[Andreas Heiduk]

Am 27.04.2018 um 20:45 schrieb Martin Ågren:
> On 27 April 2018 at 20:28, Andreas Heiduk <ashei...@gmail.com> wrote:
>> Am 27.04.2018 um 19:18 schrieb Martin Ågren:
>>> On 27 April 2018 at 19:04, Andreas Heiduk <ashei...@gmail.com> wrote:
>>>> The two '' parameters are not optional but the option
>>>> '--no-index' is. Also move the `--options` part to the same
>>>> place where the other variants show them.
>>>
>>> Should this commit message be updated after the changes you did to
>>> address Junio's comment? This text suggests you want to place --no-index
>>> in [] (and you did in v1) but you do not do that below.
>>>
>>>> All three items are already correct in the synopsis.
>>>
>>> Same here, now you actually do change things there.
>>>
>>>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>>>> Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
>>>
>>> Strictly speaking, my Reviewed-by was on another patch. I do find this
>>
>> Sorry, I've added that trailer after reading "The diff LGTM.", then
>> applied Junio's changes and forgot to remove the trailer.
>>
>>> one better though thanks to Junio's suggestion (except the mismatch with
>>> the commit message).
>>
>> I'll fix that with this:
>>
>> doc: align 'diff --no-index' in text with synopsis
> 
> s/with/and/ since they both change? It's not that the first changes to
> match the second, but they actually both change to match each other (and
> to be correct, obviously).

Corrected

> 
>> Make the two '' parameters in DESCRIPTION mandatory and
>> move the `--options` part to the same place where the other
>> variants show them. And finally make `--no-index` in SYNOPSIS
>> as mandatory as in DESCRIPTION.
> 
> Great! Junio had some good reasoning about how --no-index is
> sometimes optional, but not always. Not sure if it's worth spelling that
> out. (Although one could argue that it already did trip us up once. :-))

The post-context already explains that.

> Eric's point about "--options" vs "options" seemed right to me. If you
> address that, note that this message says "--options".

Re: [PATCH v2 6/6] doc: add note about shell quoting to revision.txt

[Andreas Heiduk]

Am 27.04.2018 um 19:36 schrieb Eric Sunshine:
> On Fri, Apr 27, 2018 at 1:04 PM, Andreas Heiduk <ashei...@gmail.com> wrote:
>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>> Reviewed-by: Junio C Hamano <gits...@pobox.com>
>> ---
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> @@ -186,6 +190,8 @@ existing tag object.
>> +  Depending on the given text the shell's word splitting rules might
>> +  require additional quoting.
> 
> s/text/&,/
> 

Fixed, Thanks

Re: [PATCH v2 2/6] doc: align 'diff --no-index' in text with synopsis

[Andreas Heiduk]

Am 27.04.2018 um 19:33 schrieb Eric Sunshine:
> On Fri, Apr 27, 2018 at 1:04 PM, Andreas Heiduk <ashei...@gmail.com> wrote:
>> The two '' parameters are not optional but the option
>> '--no-index' is. Also move the `--options` part to the same
>> place where the other variants show them.
>>
>> All three items are already correct in the synopsis.
>>
>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>> ---
>> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
>> @@ -13,7 +13,7 @@ SYNOPSIS
>> -'git diff' [options] [--no-index] [--]  
>> +'git diff' [options] --no-index [--]  
>> @@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.
>> -'git diff' --no-index [--options] [--] [...]::
>> +'git diff' [--options] --no-index [--]  ::
> 
> Not a problem introduced by this patch, but shouldn't this say
> "[options]" rather than "[--options]"? Since the aim of this patch
> series is to clean up botches and normalize documentation, perhaps it
> could also fix this oddness(?).
> 

Well, in the SYNOPSIS it is always `[options]` for all variants but in
the DESCRIPTION it is always `[--options]` for all variants. Fixing the
other variants would stretch the "subject" line of the patch a little
bit to far ;-)

Re: [PATCH v2 2/6] doc: align 'diff --no-index' in text with synopsis

[Andreas Heiduk]

Am 27.04.2018 um 19:18 schrieb Martin Ågren:
> On 27 April 2018 at 19:04, Andreas Heiduk <ashei...@gmail.com> wrote:
>> The two '' parameters are not optional but the option
>> '--no-index' is. Also move the `--options` part to the same
>> place where the other variants show them.
> 
> Should this commit message be updated after the changes you did to
> address Junio's comment? This text suggests you want to place --no-index
> in [] (and you did in v1) but you do not do that below.
> 
>> All three items are already correct in the synopsis.
> 
> Same here, now you actually do change things there.
> 
>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>> Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
> 
> Strictly speaking, my Reviewed-by was on another patch. I do find this

Sorry, I've added that trailer after reading "The diff LGTM.", then
applied Junio's changes and forgot to remove the trailer.

> one better though thanks to Junio's suggestion (except the mismatch with
> the commit message).

I'll fix that with this:

doc: align 'diff --no-index' in text with synopsis

Make the two '' parameters in DESCRIPTION mandatory and
move the `--options` part to the same place where the other
variants show them. And finally make `--no-index` in SYNOPSIS
as mandatory as in DESCRIPTION.

[PATCH v2 4/6] doc: add '-d' and '-o' for 'git push'

[Andreas Heiduk]

Add the missing `-o` shortcut for `--push-option` to the synopsis.
Add the missing `-d` shortcut for `--delete` in the main section.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
---
 Documentation/git-push.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 5b08302fc2..f2bbda6e32 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | 
--dry-run] [--receive-pack=]
   [--repo=] [-f | --force] [-d | --delete] [--prune] [-v | 
--verbose]
-  [-u | --set-upstream] [--push-option=]
+  [-u | --set-upstream] [-o  | --push-option=]
   [--[no-]signed|--signed=(true|false|if-asked)]
   [--force-with-lease[=[:]]]
   [--no-verify] [ [...]]
@@ -123,6 +123,7 @@ already exists on the remote side.
will be tab-separated and sent to stdout instead of stderr.  The full
symbolic names of the refs will be given.
 
+-d::
 --delete::
All listed refs are deleted from the remote repository. This is
the same as prefixing all refs with a colon.
-- 
2.16.2

[PATCH v2 5/6] git-svn: remove ''--add-author-from' for 'commit-diff'

[Andreas Heiduk]

The subcommand 'commit-diff' does not support the option
'--add-author-from'.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Signed-off-by: Eric Wong <e...@80x24.org>
---
 Documentation/git-svn.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index d59379ee23..e9615951d2 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -707,7 +707,7 @@ creating the branch or tag.
 config key: svn.useLogAuthor
 
 --add-author-from::
-   When committing to svn from Git (as part of 'commit-diff', 'set-tree' 
or 'dcommit'
+   When committing to svn from Git (as part of 'set-tree' or 'dcommit'
operations), if the existing log message doesn't already have a
`From:` or `Signed-off-by:` line, append a `From:` line based on the
Git commit's author string.  If you use this, then `--use-log-author`
-- 
2.16.2

[PATCH v2 3/6] doc: clarify ignore rules for git ls-files

[Andreas Heiduk]

Explain that `git ls-files --ignored` requires at least one
of the `--exclude*` options to do its job.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-ls-files.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3ac3e3a77d..f3474b2ede 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -53,7 +53,8 @@ OPTIONS
Show only ignored files in the output. When showing files in the
index, print only those matched by an exclude pattern. When
showing "other" files, show only those matched by an exclude
-   pattern.
+   pattern. Standard ignore rules are not automatically activated,
+   therefore at least one of the `--exclude*` options is required.
 
 -s::
 --stage::
-- 
2.16.2

[PATCH v2 6/6] doc: add note about shell quoting to revision.txt

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Junio C Hamano <gits...@pobox.com>
---
 Documentation/revisions.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index dfcc49c72c..c1d3a40a90 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -7,6 +7,10 @@ syntax.  Here are various ways to spell object names.  The
 ones listed near the end of this list name trees and
 blobs contained in a commit.
 
+NOTE: This document shows the "raw" syntax as seen by git. The shell
+and other UIs might require additional quoting to protect special
+characters and to avoid word splitting.
+
 '', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e'::
   The full SHA-1 object name (40-byte hexadecimal string), or
   a leading substring that is unique within the repository.
@@ -186,6 +190,8 @@ existing tag object.
   is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a
   literal '!' character, followed by 'foo'. Any other sequence beginning with
   ':/!' is reserved for now.
+  Depending on the given text the shell's word splitting rules might
+  require additional quoting.
 
 ':', e.g. 'HEAD:README', ':README', 'master:./README'::
   A suffix ':' followed by a path names the blob or tree
-- 
2.16.2

[PATCH v2 1/6] doc: improve formatting in githooks.txt

[Andreas Heiduk]

Typeset commands and similar things with as `git foo` instead of
'git foo' or 'git-foo' and add linkgit to the commands which run
the hooks.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
---
 Documentation/githooks.txt | 115 +++--
 1 file changed, 58 insertions(+), 57 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index f877f7b7cd..e3c283a174 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -31,7 +31,7 @@ Hooks can get their arguments via the environment, 
command-line
 arguments, and stdin. See the documentation for each hook below for
 details.
 
-'git init' may copy hooks to the new repository, depending on its
+`git init` may copy hooks to the new repository, depending on its
 configuration. See the "TEMPLATE DIRECTORY" section in
 linkgit:git-init[1] for details. When the rest of this document refers
 to "default hooks" it's talking about the default template shipped
@@ -45,9 +45,9 @@ HOOKS
 applypatch-msg
 ~~
 
-This hook is invoked by 'git am'.  It takes a single
+This hook is invoked by linkgit:git-am[1].  It takes a single
 parameter, the name of the file that holds the proposed commit
-log message.  Exiting with a non-zero status causes 'git am' to abort
+log message.  Exiting with a non-zero status causes `git am` to abort
 before applying the patch.
 
 The hook is allowed to edit the message file in place, and can
@@ -61,7 +61,7 @@ The default 'applypatch-msg' hook, when enabled, runs the
 pre-applypatch
 ~~
 
-This hook is invoked by 'git am'.  It takes no parameter, and is
+This hook is invoked by linkgit:git-am[1].  It takes no parameter, and is
 invoked after the patch is applied, but before a commit is made.
 
 If it exits with non-zero status, then the working tree will not be
@@ -76,33 +76,33 @@ The default 'pre-applypatch' hook, when enabled, runs the
 post-applypatch
 ~~~
 
-This hook is invoked by 'git am'.  It takes no parameter,
+This hook is invoked by linkgit:git-am[1].  It takes no parameter,
 and is invoked after the patch is applied and a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
-the outcome of 'git am'.
+the outcome of `git am`.
 
 pre-commit
 ~~
 
-This hook is invoked by 'git commit', and can be bypassed
+This hook is invoked by linkgit:git-commit[1], and can be bypassed
 with the `--no-verify` option.  It takes no parameters, and is
 invoked before obtaining the proposed commit log message and
 making a commit.  Exiting with a non-zero status from this script
-causes the 'git commit' command to abort before creating a commit.
+causes the `git commit` command to abort before creating a commit.
 
 The default 'pre-commit' hook, when enabled, catches introduction
 of lines with trailing whitespaces and aborts the commit when
 such a line is found.
 
-All the 'git commit' hooks are invoked with the environment
+All the `git commit` hooks are invoked with the environment
 variable `GIT_EDITOR=:` if the command will not bring up an editor
 to modify the commit message.
 
 prepare-commit-msg
 ~~
 
-This hook is invoked by 'git commit' right after preparing the
+This hook is invoked by linkgit:git-commit[1] right after preparing the
 default log message, and before the editor is started.
 
 It takes one to three parameters.  The first is the name of the file
@@ -114,7 +114,7 @@ commit is a merge or a `.git/MERGE_MSG` file exists); 
`squash`
 (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by
 a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given).
 
-If the exit status is non-zero, 'git commit' will abort.
+If the exit status is non-zero, `git commit` will abort.
 
 The purpose of the hook is to edit the message file in place, and
 it is not suppressed by the `--no-verify` option.  A non-zero exit
@@ -127,7 +127,7 @@ help message found in the commented portion of the commit 
template.
 commit-msg
 ~~
 
-This hook is invoked by 'git commit' and 'git merge', and can be
+This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and 
can be
 bypassed with the `--no-verify` option.  It takes a single parameter,
 the name of the file that holds the proposed commit log message.
 Exiting with a non-zero status causes the command to abort.
@@ -143,16 +143,16 @@ The default 'commit-msg' hook, when enabled, detects 
duplicate
 post-commit
 ~~~
 
-This hook is invoked by 'git commit'. It takes no parameters, and is
+This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is
 invoked after a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
-the outcome of 'git commit'.
+the outcome of `git commit`.
 
 pre-rebase
 ~~
 
-This hook is called by 'git rebase' and can be used to prevent a
+This hook

[PATCH v2 2/6] doc: align 'diff --no-index' in text with synopsis

[Andreas Heiduk]

The two '' parameters are not optional but the option
'--no-index' is. Also move the `--options` part to the same
place where the other variants show them.

All three items are already correct in the synopsis.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Reviewed-by: Martin Ågren <martin.ag...@gmail.com>
---
 Documentation/git-diff.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index b0c1bb95c8..6593b58299 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 'git diff' [options] --cached [] [--] [...]
 'git diff' [options]   [--] [...]
 'git diff' [options]  
-'git diff' [options] [--no-index] [--]  
+'git diff' [options] --no-index [--]  
 
 DESCRIPTION
 ---
@@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.
further add to the index but you still haven't.  You can
stage these changes by using linkgit:git-add[1].
 
-'git diff' --no-index [--options] [--] [...]::
+'git diff' [--options] --no-index [--]  ::
 
This form is to compare the given two paths on the
filesystem.  You can omit the `--no-index` option when
-- 
2.16.2

[PATCH v2 0/6] Some doc-fixes

[Andreas Heiduk]

This reroll incorporates the comments of the first version, including a
"large scale" rewrtie of githooks.txt. I'v added "Reviewed-by" and
"Signed-off-by" as appropriate.

Andreas Heiduk (6):
  doc: improve formatting in githooks.txt
  doc: align 'diff --no-index' in text with synopsis
  doc: clarify ignore rules for git ls-files
  doc: add '-d' and '-o' for 'git push'
  git-svn: remove ''--add-author-from' for 'commit-diff'
  doc: add note about shell quoting to revision.txt

 Documentation/git-diff.txt |   4 +-
 Documentation/git-ls-files.txt |   3 +-
 Documentation/git-push.txt |   3 +-
 Documentation/git-svn.txt  |   2 +-
 Documentation/githooks.txt | 115 +
 Documentation/revisions.txt|   6 +++
 6 files changed, 71 insertions(+), 62 deletions(-)

-- 
2.16.2

Re: [PATCH 5/6] git-svn: commit-diff does not support --add-author-from

[Andreas Heiduk]

Am 17.04.2018 um 08:18 schrieb Eric Wong:
> Andreas Heiduk <ashei...@gmail.com> wrote:
>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
> 
> Thanks.
> Signed-off-by: Eric Wong <e...@80x24.org>
> 
> And pushed for Junio:
[...]

I'd like to keep the patches together, so I borrow your 'Signed-off-By'
from the commit and do a complete reroll of this mini-series.

Re: fixup! [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

Am 12.04.2018 um 21:36 schrieb Martin Ågren:
> On 11 April 2018 at 23:08, Andreas Heiduk <ashei...@gmail.com> wrote:
>> - reflow some paragraphs
>> ---
>>  Documentation/githooks.txt | 14 +++---
>>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> I have reviewed the resulting githooks.txt. See the diff below for two
> more instances that I found. For the second hunk, I have difficulties
> parsing that paragraph, but I still claim those should be backticks and
> *git* read-tree...
>
> Martin

I've added the fixes for the next reroll and put you into a Reviewed-by
Trailer :-)

Andreas

Re: RFC: How should we handle un-deleted remote branches?

[Andreas Heiduk]

Am 22.04.2018 um 13:17 schrieb Ævar Arnfjörð Bjarmason:
> 
> On Sun, Apr 22 2018, Andreas Heiduk wrote:
> 
>> Am 20.04.2018 um 14:14 schrieb Ævar Arnfjörð Bjarmason:
>>> But this is a possible work-around:
>>>
>>> git init /tmp/empty.git
>>> git remote add avar file:///tmp/empty.git
>>> git remote prune avar
>>> git remote remove avar
>>
>> This won't do it also?
>>
>>  git remote prune origin
> 
> Yes, in this particular case, but that's just emergent behavior in how
> we handle refspec prunign, and the fact that it "works" is arguably a
> bug in "prune". i.e. this:

Its not emergent because "origin" is the other remote responsible for
that ref and cleaning stuff "belonging" to the remote is the job
description (I'm arguing from a user's perspective, not as a git-developer).

> 
> (
> rm -rf /tmp/git &&
> git clone --bare --mirror g...@github.com:git/git.git /tmp/git &&
> cd /tmp/git &&
> git remote add avar g...@github.com:avar/git.git &&
> git remote add peff g...@github.com:peff/git.git &&
> git fetch --all &&
> git remote remove avar &&
> git remote prune origin
> )
> 
> Will delete all the avar/* and peff/* branches, even though I still have
> a "peff" remote.

Exactly my point: When you are in a the bad situation of "shared
responsibility", then there is no easy and always correct way out,
because there are uncountable possible situations.

To give another, slightly modified example expanding the problem space:

(
rm -rf /tmp/git &&
git clone --bare --mirror https://github.com/git/git.git /tmp/git &&
cd /tmp/git &&
git remote add github https://github.com/avar/git.git &&
git fetch github &&
git fetch origin &&
# note new fetches for "github/master" using with "(forced update)"
)

For ... reasons the first repo publishes some references like

github/maint
github/master
github/pu

So when this repo is mirrored AND another, suitably named remote is
added then there will be also namespace conflicts. You can call

git fetch github
git fetch origin

in a loop and most likely each fetch will update the same refs, always
toggling between two states.

So: not only "remote remove" and "remote prune" are at stake but every
command handling remote references.

How should "git remote remove github" work in both situations? Remove
the refs/remotes/github/master & co? remove them only if the last fetch
was for "github" but not when the last update was for "origin"? Should
"git fetch" use the same logic?

So it seems better to me to avoid that bad situation altogether. Don't
allow overlapping/conflicting refspecs when adding a new remote. Using
*your* last examples both

> git remote add avar g...@github.com:avar/git.git &&
> git remote add peff g...@github.com:peff/git.git &&

should have failed and hence the "prune" problems won't exist. Same for
my example.

>> Possible 5):
>>
>>  Don't fix "git remote remove" but "git remote add" to complain that its
>> ref-namespace is already occupied by some other remote. Add "--force"
>> for the experts.
> 
> Indeed, that's another bug here, i.e. in the above example:
> 
> git remote remove peff && # won't delete peff/ branches
> git remote add peff g...@github.com:peff/git.git
> 
> Will happily add the "peff" remote again, even though as you point out
> it could be an entirely different remote.

Ummm. That was not my point. My is: "git clone --mirror" uses a refspec

fetch = +refs/*:refs/*

and hence "occupies" the complete "refs/*" namespace. So adding another
remote (for the first time or for the second time is as irrelevant as
the url) will use

fetch = +refs/heads/*:refs/remotes/peff/*

and now the "refs/remotes/peff/*" part is in conflict with "refs/*" from
above. The conflict exists not only for "prune" or "remove" but also for
"fetch", "rename" (didn't check) .

This kind of conflict should not be allowed right from the start - when
the first "git remote add peff..." is executed. Then prune, remove AND
fetch would be OK.

Re: RFC: How should we handle un-deleted remote branches?

[Andreas Heiduk]

Am 20.04.2018 um 14:14 schrieb Ævar Arnfjörð Bjarmason:
> But this is a possible work-around:
> 
> git init /tmp/empty.git
> git remote add avar file:///tmp/empty.git
> git remote prune avar
> git remote remove avar

This won't do it also?

git remote prune origin


> I started to patch this, but I'm not sure what to do here. we could do
> some combination of:
> 
>  0. Just document the current behavior and leave it.
> 
>  1. Dig further down to see what other remotes reference these refs, and
> just ignore any refspecs that don't explicitly reference
> refs/remotes//*.
> 
> I.e. isn't the intention here to preserve a case where you have two
> URLs for the same effective remote, not whene you have something
> like a --mirror refspec? Unfortunately I can't ask the original
> author :(
> 
>  2. Warn about each ref we didn't delete, or at least warn saying
> there's undeleted refs under refs/remotes//*.
> 
>  3. Make 'git remote remove --force-deletion ' (or whatever the
> flag is called) be a thing. But unless we do the next item this
> won't be useful.
> 
>  4. Make 'git remote prune ' work in cases where we don't have a
> remote called  anymore, just falling back to deleting
> refs/remotes/. In this case 'git remote remove
> --force-deletion ' would also do the same thing.

Possible 5):

Don't fix "git remote remove" but "git remote add" to complain that its
ref-namespace is already occupied by some other remote. Add "--force"
for the experts.

fixup! [PATCH 2/6] doc: align 'diff --no-index' in text with synopsis

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-diff.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index ee1c509bd3..6593b58299 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 'git diff' [options] --cached [] [--] [...]
 'git diff' [options]   [--] [...]
 'git diff' [options]  
-'git diff' [options] [--no-index] [--]  
+'git diff' [options] --no-index [--]  
 
 DESCRIPTION
 ---
@@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.
further add to the index but you still haven't.  You can
stage these changes by using linkgit:git-add[1].
 
-'git diff' [--options] [--no-index] [--]  ::
+'git diff' [--options] --no-index [--]  ::
 
This form is to compare the given two paths on the
filesystem.  You can omit the `--no-index` option when
-- 
2.16.2

fixup! [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

- reflow some paragraphs
---
 Documentation/githooks.txt | 14 +++---
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index be31376767..ab5ce80e13 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -194,10 +194,10 @@ for an example of how to do this.
 pre-push
 
 
-This hook is called by linkgit:git-push[1] and can be used to prevent a push 
from taking
-place.  The hook is called with two parameters which provide the name and
-location of the destination remote, if a named remote is not being used both
-values will be the same.
+This hook is called by linkgit:git-push[1] and can be used to prevent
+a push from taking place.  The hook is called with two parameters
+which provide the name and location of the destination remote, if a
+named remote is not being used both values will be the same.
 
 Information about what is to be pushed is provided on the hook's standard
 input with lines of the form:
@@ -410,9 +410,9 @@ with the difference between the branches.
 pre-auto-gc
 ~~~
 
-This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It takes no 
parameter, and
-exiting with non-zero status from this script causes the `git gc --auto`
-to abort.
+This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It
+takes no parameter, and exiting with non-zero status from this script
+causes the `git gc --auto` to abort.
 
 post-rewrite
 
-- 
2.16.2

fixup! [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

- add linkgit: to callers of hooks
- change 'git-foo' and similar to `git foo`
- add some more `` for fsmonitor
---
 Documentation/githooks.txt | 101 +++--
 1 file changed, 51 insertions(+), 50 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 070e745b41..be31376767 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -31,7 +31,7 @@ Hooks can get their arguments via the environment, 
command-line
 arguments, and stdin. See the documentation for each hook below for
 details.
 
-'git init' may copy hooks to the new repository, depending on its
+`git init` may copy hooks to the new repository, depending on its
 configuration. See the "TEMPLATE DIRECTORY" section in
 linkgit:git-init[1] for details. When the rest of this document refers
 to "default hooks" it's talking about the default template shipped
@@ -45,9 +45,9 @@ HOOKS
 applypatch-msg
 ~~
 
-This hook is invoked by 'git am'.  It takes a single
+This hook is invoked by linkgit:git-am[1].  It takes a single
 parameter, the name of the file that holds the proposed commit
-log message.  Exiting with a non-zero status causes 'git am' to abort
+log message.  Exiting with a non-zero status causes `git am` to abort
 before applying the patch.
 
 The hook is allowed to edit the message file in place, and can
@@ -61,7 +61,7 @@ The default 'applypatch-msg' hook, when enabled, runs the
 pre-applypatch
 ~~
 
-This hook is invoked by 'git am'.  It takes no parameter, and is
+This hook is invoked by linkgit:git-am[1].  It takes no parameter, and is
 invoked after the patch is applied, but before a commit is made.
 
 If it exits with non-zero status, then the working tree will not be
@@ -76,7 +76,7 @@ The default 'pre-applypatch' hook, when enabled, runs the
 post-applypatch
 ~~~
 
-This hook is invoked by 'git am'.  It takes no parameter,
+This hook is invoked by linkgit:git-am[1].  It takes no parameter,
 and is invoked after the patch is applied and a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
@@ -85,24 +85,24 @@ the outcome of 'git am'.
 pre-commit
 ~~
 
-This hook is invoked by 'git commit', and can be bypassed
+This hook is invoked by linkgit:git-commit[1], and can be bypassed
 with the `--no-verify` option.  It takes no parameters, and is
 invoked before obtaining the proposed commit log message and
 making a commit.  Exiting with a non-zero status from this script
-causes the 'git commit' command to abort before creating a commit.
+causes the `git commit` command to abort before creating a commit.
 
 The default 'pre-commit' hook, when enabled, catches introduction
 of lines with trailing whitespaces and aborts the commit when
 such a line is found.
 
-All the 'git commit' hooks are invoked with the environment
+All the `git commit` hooks are invoked with the environment
 variable `GIT_EDITOR=:` if the command will not bring up an editor
 to modify the commit message.
 
 prepare-commit-msg
 ~~
 
-This hook is invoked by 'git commit' right after preparing the
+This hook is invoked by linkgit:git-commit[1] right after preparing the
 default log message, and before the editor is started.
 
 It takes one to three parameters.  The first is the name of the file
@@ -114,7 +114,7 @@ commit is a merge or a `.git/MERGE_MSG` file exists); 
`squash`
 (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by
 a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given).
 
-If the exit status is non-zero, 'git commit' will abort.
+If the exit status is non-zero, `git commit` will abort.
 
 The purpose of the hook is to edit the message file in place, and
 it is not suppressed by the `--no-verify` option.  A non-zero exit
@@ -127,7 +127,7 @@ help message found in the commented portion of the commit 
template.
 commit-msg
 ~~
 
-This hook is invoked by 'git commit' and 'git merge', and can be
+This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and 
can be
 bypassed with the `--no-verify` option.  It takes a single parameter,
 the name of the file that holds the proposed commit log message.
 Exiting with a non-zero status causes the command to abort.
@@ -143,16 +143,16 @@ The default 'commit-msg' hook, when enabled, detects 
duplicate
 post-commit
 ~~~
 
-This hook is invoked by 'git commit'. It takes no parameters, and is
+This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is
 invoked after a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
-the outcome of 'git commit'.
+the outcome of `git commit`.
 
 pre-rebase
 ~~
 
-This hook is called by 'git rebase' and can be used to prevent a
+This hook is called by linkgit:git-rebase[1] and can be used to prevent a
 branch from getting rebased.  The hook may be called with one or
 two parameters.  The first parameter is the 

Re: [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

So the following two fixups should cleanup that page considerably.

Re: [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

Am 10.04.2018 um 21:13 schrieb Martin Ågren:
> On 10 April 2018 at 20:32, Andreas Heiduk <ashei...@gmail.com> wrote:
>> The section 'post-rewrite' in 'githooks.txt' renders only one command
>> using backticks (`git commit`) but the other commands using single quotes
>> ('git-rebase'). Align this formatting to use single quotes.
>>
>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>> ---
>>  Documentation/githooks.txt | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
>> index f877f7b7cd..070e745b41 100644
>> --- a/Documentation/githooks.txt
>> +++ b/Documentation/githooks.txt
>> @@ -417,8 +417,8 @@ to abort.
>>  post-rewrite
>>  
>>
>> -This hook is invoked by commands that rewrite commits (`git commit
>> ---amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call
>> +This hook is invoked by commands that rewrite commits ('git commit
>> +--amend', 'git-rebase'; currently 'git-filter-branch' does 'not' call
>>  it!).  Its first argument denotes the command it was invoked by:
>>  currently one of `amend` or `rebase`.  Further command-dependent
>>  arguments may be passed in the future.
> 
> Hmm, I wonder if that is actually intentional. `git commit --amend`
> could be run exactly like that and would do what this paragraph expects
> of it. The 'git-rebase' is a Git subcommand name, i.e., not some
> copy-paste command-line ready for use. If it were something like `git
> rebase -i HEAD~5`, I would expect the backticks.

That page mostly uses single quotes and no dash ('git send-email')for
formatting. Reading 'CodingGuidelines' my understanding is, that git
commands should be typeset with backticks, no dash (`git send-email`). 
So 'git-rebase' (an similar) *should* be typeset as `git rebase`. But
doing so consistently would be a full-diff for this manual page.

Should I do this?

> 
> A second discrepancy is the dash in "git commit" vs "git-rebase" and
> "git-ls-remote". That could perhaps be explained by the same reasoning.
> 
> Martin
> 

Re: [PATCH 2/6] doc: align 'diff --no-index' in text with synopsis

[Andreas Heiduk]

Am 10.04.2018 um 21:14 schrieb Martin Ågren:
> On 10 April 2018 at 20:32, Andreas Heiduk <ashei...@gmail.com> wrote:
>> Comparing
> 
> That first line should probably not be there. The diff LGTM.
> 
> Martin
> 

ACK, Thanks

[PATCH 6/6] doc: add note about shell quoting to revision.txt

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/revisions.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index dfcc49c72c..c1d3a40a90 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -7,6 +7,10 @@ syntax.  Here are various ways to spell object names.  The
 ones listed near the end of this list name trees and
 blobs contained in a commit.
 
+NOTE: This document shows the "raw" syntax as seen by git. The shell
+and other UIs might require additional quoting to protect special
+characters and to avoid word splitting.
+
 '', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e'::
   The full SHA-1 object name (40-byte hexadecimal string), or
   a leading substring that is unique within the repository.
@@ -186,6 +190,8 @@ existing tag object.
   is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a
   literal '!' character, followed by 'foo'. Any other sequence beginning with
   ':/!' is reserved for now.
+  Depending on the given text the shell's word splitting rules might
+  require additional quoting.
 
 ':', e.g. 'HEAD:README', ':README', 'master:./README'::
   A suffix ':' followed by a path names the blob or tree
-- 
2.16.2

[PATCH 5/6] git-svn: commit-diff does not support --add-author-from

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-svn.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 636e09048e..11aefadf7a 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -700,7 +700,7 @@ creating the branch or tag.
 config key: svn.useLogAuthor
 
 --add-author-from::
-   When committing to svn from Git (as part of 'commit-diff', 'set-tree' 
or 'dcommit'
+   When committing to svn from Git (as part of 'set-tree' or 'dcommit'
operations), if the existing log message doesn't already have a
`From:` or `Signed-off-by:` line, append a `From:` line based on the
Git commit's author string.  If you use this, then `--use-log-author`
-- 
2.16.2

[PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

The section 'post-rewrite' in 'githooks.txt' renders only one command
using backticks (`git commit`) but the other commands using single quotes
('git-rebase'). Align this formatting to use single quotes.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/githooks.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index f877f7b7cd..070e745b41 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -417,8 +417,8 @@ to abort.
 post-rewrite
 
 
-This hook is invoked by commands that rewrite commits (`git commit
---amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call
+This hook is invoked by commands that rewrite commits ('git commit
+--amend', 'git-rebase'; currently 'git-filter-branch' does 'not' call
 it!).  Its first argument denotes the command it was invoked by:
 currently one of `amend` or `rebase`.  Further command-dependent
 arguments may be passed in the future.
-- 
2.16.2

[PATCH 3/6] doc: clarify ignore rules for git ls-files

[Andreas Heiduk]

Explain that `git ls-files --ignored` requires at least one
of the `--exclude*` options to do its job.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-ls-files.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3ac3e3a77d..f3474b2ede 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -53,7 +53,8 @@ OPTIONS
Show only ignored files in the output. When showing files in the
index, print only those matched by an exclude pattern. When
showing "other" files, show only those matched by an exclude
-   pattern.
+   pattern. Standard ignore rules are not automatically activated,
+   therefore at least one of the `--exclude*` options is required.
 
 -s::
 --stage::
-- 
2.16.2

[PATCH 4/6] doc: added '-d' and '-q' for 'git push'

[Andreas Heiduk]

Add the missing `-o` shortcut for `--push-option` to the synposis.
Add the missing `-d` shortcut for `--delete` in the main section.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-push.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 5b08302fc2..f2bbda6e32 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | 
--dry-run] [--receive-pack=]
   [--repo=] [-f | --force] [-d | --delete] [--prune] [-v | 
--verbose]
-  [-u | --set-upstream] [--push-option=]
+  [-u | --set-upstream] [-o  | --push-option=]
   [--[no-]signed|--signed=(true|false|if-asked)]
   [--force-with-lease[=[:]]]
   [--no-verify] [ [...]]
@@ -123,6 +123,7 @@ already exists on the remote side.
will be tab-separated and sent to stdout instead of stderr.  The full
symbolic names of the refs will be given.
 
+-d::
 --delete::
All listed refs are deleted from the remote repository. This is
the same as prefixing all refs with a colon.
-- 
2.16.2

[PATCH 0/6] Some doc-fixes

[Andreas Heiduk]

I'm flushing a queue of small fixes to the docs. Handling these
indiviually is just to much hassle - at least I hope so :-)

Andreas Heiduk (6):
  doc: fix formatting inconsistency in githooks.txt
  doc: align 'diff --no-index' in text with synopsis
  doc: clarify ignore rules for git ls-files
  doc: added '-d' and '-q' for 'git push'
  git-svn: commit-diff does not support --add-author-from
  doc: add note about shell quoting to revision.txt

 Documentation/git-diff.txt | 2 +-
 Documentation/git-ls-files.txt | 3 ++-
 Documentation/git-push.txt | 3 ++-
 Documentation/git-svn.txt  | 2 +-
 Documentation/githooks.txt | 4 ++--
 Documentation/revisions.txt| 6 ++
 6 files changed, 14 insertions(+), 6 deletions(-)

-- 
2.16.2

Re: [PATCH v3] git-svn: allow empty email-address using authors-prog and authors-file

[Andreas Heiduk]

Am 05.04.2018 um 09:51 schrieb Eric Wong:
> Thanks for the update.  The patch itself looks good, but I
> noticed one --show-item isn't supported on SVN 1.8.10 for me.

--show-item is indeed a 1.9.0 thing:

https://subversion.apache.org/docs/release-notes/1.9.html#svn-info-item

> I've tested the following on both SVN 1.8.10 and 1.9.5:
> 
> --- a/t/t9138-git-svn-authors-prog.sh
> +++ b/t/t9138-git-svn-authors-prog.sh
> @@ -83,7 +83,8 @@ test_expect_success 'authors-prog imported user without 
> email' '
>  test_expect_success 'imported without authors-prog and authors-file' '
>   svn mkdir -m hh --username hh "$svnrepo"/hh &&
>   (
> - uuid=$(svn info --show-item=repos-uuid "$svnrepo") &&
> + uuid=$(svn info "$svnrepo" |
> + sed -n "s/^Repository UUID: //p") &&
>   cd x &&
>   git svn fetch &&
>   git rev-list -1 --pretty=raw refs/remotes/git-svn | \
> 
> Can you confirm it's OK for you?  Thanks.

Looks good, works for me.

Do you squash this patch with with my commit or do you need a reroll?

[PATCH v3] git-svn: allow empty email-address using authors-prog and authors-file

[Andreas Heiduk]

The email address in --authors-file and --authors-prog can be empty but
git-svn translated it into a fictional email address in the form

jondoe <jondoe@6aafaa21e0fb4338a68ab372a049893d>

containing the SVN repository UUID. Now git-svn behaves like git-commit:
If the email is *explicitly* set to the empty string using '<>', the
commit does not contain an email address, only the name:

jondoe <>

Allowing to remove the email address *intentionally* prevents automatic
systems from sending emails to those fictional addresses and avoids
cluttering the log output with unnecessary stuff.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-svn.txt   |  8 +---
 perl/Git/SVN.pm | 13 ++---
 t/t9130-git-svn-authors-file.sh | 14 ++
 t/t9138-git-svn-authors-prog.sh | 25 -
 4 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index b858374649..d59379ee23 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -635,7 +635,8 @@ config key: svn.findcopiesharder
 
 -A::
 --authors-file=::
-   Syntax is compatible with the file used by 'git cvsimport':
+   Syntax is compatible with the file used by 'git cvsimport' but
+   an empty email address can be supplied with '<>':
 +
 
loginname = Joe User <u...@example.com>
@@ -654,8 +655,9 @@ config key: svn.authorsfile
If this option is specified, for each SVN committer name that
does not exist in the authors file, the given file is executed
with the committer name as the first argument.  The program is
-   expected to return a single line of the form "Name ",
-   which will be treated as if included in the authors file.
+   expected to return a single line of the form "Name " or
+   "Name <>", which will be treated as if included in the authors
+   file.
 +
 Due to historical reasons a relative 'filename' is first searched
 relative to the current directory for 'init' and 'clone' and relative
diff --git a/perl/Git/SVN.pm b/perl/Git/SVN.pm
index bc4eed3d75..945ca4db2b 100644
--- a/perl/Git/SVN.pm
+++ b/perl/Git/SVN.pm
@@ -1482,7 +1482,6 @@ sub call_authors_prog {
}
if ($author =~ /^\s*(.+?)\s*<(.*)>\s*$/) {
my ($name, $email) = ($1, $2);
-   $email = undef if length $2 == 0;
return [$name, $email];
} else {
die "Author: $orig_author: $::_authors_prog returned "
@@ -2020,8 +2019,8 @@ sub make_log_entry {
remove_username($full_url);
$log_entry{metadata} = "$full_url\@$r $uuid";
$log_entry{svm_revision} = $r;
-   $email ||= "$author\@$uuid";
-   $commit_email ||= "$author\@$uuid";
+   $email = "$author\@$uuid" unless defined $email;
+   $commit_email = "$author\@$uuid" unless defined $commit_email;
} elsif ($self->use_svnsync_props) {
my $full_url = canonicalize_url(
add_path_to_url( $self->svnsync->{url}, $self->path )
@@ -2029,15 +2028,15 @@ sub make_log_entry {
remove_username($full_url);
my $uuid = $self->svnsync->{uuid};
$log_entry{metadata} = "$full_url\@$rev $uuid";
-   $email ||= "$author\@$uuid";
-   $commit_email ||= "$author\@$uuid";
+   $email = "$author\@$uuid" unless defined $email;
+   $commit_email = "$author\@$uuid" unless defined $commit_email;
} else {
my $url = $self->metadata_url;
remove_username($url);
my $uuid = $self->rewrite_uuid || $self->ra->get_uuid;
$log_entry{metadata} = "$url\@$rev " . $uuid;
-   $email ||= "$author\@" . $uuid;
-   $commit_email ||= "$author\@" . $uuid;
+   $email = "$author\@$uuid" unless defined $email;
+   $commit_email = "$author\@$uuid" unless defined $commit_email;
}
$log_entry{name} = $name;
$log_entry{email} = $email;
diff --git a/t/t9130-git-svn-authors-file.sh b/t/t9130-git-svn-authors-file.sh
index 41264818cc..6af6daf461 100755
--- a/t/t9130-git-svn-authors-file.sh
+++ b/t/t9130-git-svn-authors-file.sh
@@ -108,6 +108,20 @@ test_expect_success !MINGW 'fresh clone with 
svn.authors-file in config' '
)
 '
 
+cat >> svn-authors <
+EOF
+
+test_expect_success 'authors-file imported user without email' '
+   svn_cmd mkdir -m aa/branches/ff --username ff "$svnrepo

Re: [PATCH v2 2/2] git-svn: allow empty email-address in authors-prog and authors-file

[Andreas Heiduk]

Am 19.03.2018 um 00:04 schrieb Eric Wong:
> Andreas Heiduk <ashei...@gmail.com> wrote:
>> The email address in --authors-file and --authors-prog can be empty but
>> git-svn translated it into a syntethic email address in the form
>> $USERNAME@$REPO_UUID. Now git-svn behaves like git-commit: If the email
>> is explicitly set to the empty string, the commit does not contain
>> an email address.
> 
> What is missing is WHY "<>" is preferable to "<$USERNAME@$REPO_UUID>".
>
> $USERNAME is good anyways since projects/organizations tie their
> SVN usernames to email usernames via LDAP, making it easy to
> infer their email address from $USERNAME.  The latter can also
> be used to disambiguate authors if they happen to have the same
> real name.

That's still available and it's even still the default.

But: If the user of git-svn takes the burden of writing an authors
script or maintaining an authors file then he should have full control
over the result as long as git can handle the output reasonably.
Currently that's the case for git but not for git-svn.

Git can handle empty emails quite nicely:

> git -c user.email= commit --allow-empty -m "foo"
> git show --format=raw HEAD | egrep "author|committer"
author jondoe <> 1521495217 +0100
committer jondoe <> 1521495217 +0100

Doing the same with current git-svn requires a filter-branch followed
by `rm -r .git/svn/`  followed by `git svn fetch` to recreate the
rev_map files. That would be feasible for a one-time conversion but
not in a situation where SVN is live and the master repository.

>
> "<>" is completely meaningless.
>

Not quite. The "<>" is not the only information - there is still the
mandatory "name" part. So the commit id

jondoe <>

just means: "There is intentionally no email address." For an
internal, ephemeral repository that can be OK. It has the advantage,
that no automatic system (Jira, Jenkins, ...) will try to send emails to 

jondoe <jondoe@6aafaa21e0fb4338a68ab372a049893d>

Additionally the log output isn't cluttered with irrelevant stuff. :-)

And last but not least we don't have to hunt down names long gone by and
already deleted in LDAP. In that case the UUID doesn't help either.


Further steps: Eric Sunshine mentioned [1] that you might have concerns about
the change of behavior per se. For me the patch is not so much a new feature but
a bugfix bringing git-svn in sync with git itself. Adding an option parameter 
to enable the new behavior seems strange to me. But there might be other ways
to achieve the same effect:

- changing the output format of the file and prog: empty emails could be 
  marked by a syntax which is invalid so far.

- OR (if some change of behaviour is acceptable) the script could evaluate
  a new environment variable like GIT_SVN_UUID to compose the 
  `<$user@$uuid>` part itself.

- OR just mention it in the relaese notes ;-)

- OR [please insert ideas here]


[1] 
https://public-inbox.org/git/capig+cq1si-avazf_1kf4yx9+egd9tgudvp7npj3uyxy1pl...@mail.gmail.com/

Re: [PATCH v2 0/2] git-svn: --author-prog improvements

[Andreas Heiduk]

No comments on this one?

[PATCH v2 1/2] git-svn: search --authors-prog in PATH too

[Andreas Heiduk]

In 36db1eddf9 ("git-svn: add --authors-prog option", 2009-05-14) the path
to authors-prog was made absolute because git-svn changes the current
directory in some situations. This makes sense if the program is part of
the repository but prevents searching via $PATH.

The old behaviour is still retained, but if the file does not exists, then
authors-prog is searched for in $PATH as any other command.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Signed-off-by: Eric Wong <e...@80x24.org>
---
 Documentation/git-svn.txt | 5 +
 git-svn.perl  | 3 ++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 636e09048e..b858374649 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -657,6 +657,11 @@ config key: svn.authorsfile
expected to return a single line of the form "Name ",
which will be treated as if included in the authors file.
 +
+Due to historical reasons a relative 'filename' is first searched
+relative to the current directory for 'init' and 'clone' and relative
+to the root of the working tree for 'fetch'. If 'filename' is
+not found, it is searched like any other command in '$PATH'.
++
 [verse]
 config key: svn.authorsProg
 
diff --git a/git-svn.perl b/git-svn.perl
index a6b6c3e40c..050f2a36f4 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -374,7 +374,8 @@ version() if $_version;
 usage(1) unless defined $cmd;
 load_authors() if $_authors;
 if (defined $_authors_prog) {
-   $_authors_prog = "'" . File::Spec->rel2abs($_authors_prog) . "'";
+   my $abs_file = File::Spec->rel2abs($_authors_prog);
+   $_authors_prog = "'" . $abs_file . "'" if -x $abs_file;
 }
 
 unless ($cmd =~ /^(?:clone|init|multi-init|commit-diff)$/) {
-- 
2.16.2

[PATCH v2 2/2] git-svn: allow empty email-address in authors-prog and authors-file

[Andreas Heiduk]

The email address in --authors-file and --authors-prog can be empty but
git-svn translated it into a syntethic email address in the form
$USERNAME@$REPO_UUID. Now git-svn behaves like git-commit: If the email
is explicitly set to the empty string, the commit does not contain
an email address.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-svn.txt   |  8 +---
 perl/Git/SVN.pm | 13 ++---
 t/t9130-git-svn-authors-file.sh | 14 ++
 t/t9138-git-svn-authors-prog.sh | 25 -
 4 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index b858374649..d59379ee23 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -635,7 +635,8 @@ config key: svn.findcopiesharder
 
 -A::
 --authors-file=::
-   Syntax is compatible with the file used by 'git cvsimport':
+   Syntax is compatible with the file used by 'git cvsimport' but
+   an empty email address can be supplied with '<>':
 +
 
loginname = Joe User <u...@example.com>
@@ -654,8 +655,9 @@ config key: svn.authorsfile
If this option is specified, for each SVN committer name that
does not exist in the authors file, the given file is executed
with the committer name as the first argument.  The program is
-   expected to return a single line of the form "Name ",
-   which will be treated as if included in the authors file.
+   expected to return a single line of the form "Name " or
+   "Name <>", which will be treated as if included in the authors
+   file.
 +
 Due to historical reasons a relative 'filename' is first searched
 relative to the current directory for 'init' and 'clone' and relative
diff --git a/perl/Git/SVN.pm b/perl/Git/SVN.pm
index bc4eed3d75..945ca4db2b 100644
--- a/perl/Git/SVN.pm
+++ b/perl/Git/SVN.pm
@@ -1482,7 +1482,6 @@ sub call_authors_prog {
}
if ($author =~ /^\s*(.+?)\s*<(.*)>\s*$/) {
my ($name, $email) = ($1, $2);
-   $email = undef if length $2 == 0;
return [$name, $email];
} else {
die "Author: $orig_author: $::_authors_prog returned "
@@ -2020,8 +2019,8 @@ sub make_log_entry {
remove_username($full_url);
$log_entry{metadata} = "$full_url\@$r $uuid";
$log_entry{svm_revision} = $r;
-   $email ||= "$author\@$uuid";
-   $commit_email ||= "$author\@$uuid";
+   $email = "$author\@$uuid" unless defined $email;
+   $commit_email = "$author\@$uuid" unless defined $commit_email;
} elsif ($self->use_svnsync_props) {
my $full_url = canonicalize_url(
add_path_to_url( $self->svnsync->{url}, $self->path )
@@ -2029,15 +2028,15 @@ sub make_log_entry {
remove_username($full_url);
my $uuid = $self->svnsync->{uuid};
$log_entry{metadata} = "$full_url\@$rev $uuid";
-   $email ||= "$author\@$uuid";
-   $commit_email ||= "$author\@$uuid";
+   $email = "$author\@$uuid" unless defined $email;
+   $commit_email = "$author\@$uuid" unless defined $commit_email;
} else {
my $url = $self->metadata_url;
remove_username($url);
my $uuid = $self->rewrite_uuid || $self->ra->get_uuid;
$log_entry{metadata} = "$url\@$rev " . $uuid;
-   $email ||= "$author\@" . $uuid;
-   $commit_email ||= "$author\@" . $uuid;
+   $email = "$author\@$uuid" unless defined $email;
+   $commit_email = "$author\@$uuid" unless defined $commit_email;
}
$log_entry{name} = $name;
$log_entry{email} = $email;
diff --git a/t/t9130-git-svn-authors-file.sh b/t/t9130-git-svn-authors-file.sh
index 41264818cc..6af6daf461 100755
--- a/t/t9130-git-svn-authors-file.sh
+++ b/t/t9130-git-svn-authors-file.sh
@@ -108,6 +108,20 @@ test_expect_success !MINGW 'fresh clone with 
svn.authors-file in config' '
)
 '
 
+cat >> svn-authors <
+EOF
+
+test_expect_success 'authors-file imported user without email' '
+   svn_cmd mkdir -m aa/branches/ff --username ff "$svnrepo/aa/branches/ff" 
&&
+   (
+   cd aa-work &&
+   git svn fetch --authors-file=../svn-authors &&
+   git rev-list -1 --pretty=raw refs/remotes/origin/ff | \
+ grep "^author FFF FFF <> "
+   )
+   '
+
 test_

[PATCH v2 0/2] git-svn: --author-prog improvements

[Andreas Heiduk]

The first patch has been queued by Eric Wong but by Junio Hamano, so
I'm not sure what's the expected procedure. I#M posting it again just
in case.

The second patch has grown up with some documentation and some tests.

Andreas Heiduk (2):
  git-svn: search --authors-prog in PATH too
  git-svn: allow empty email-address in authors-prog and authors-file

 Documentation/git-svn.txt   | 13 ++---
 git-svn.perl|  3 ++-
 perl/Git/SVN.pm | 13 ++---
 t/t9130-git-svn-authors-file.sh | 14 ++
 t/t9138-git-svn-authors-prog.sh | 25 -
 5 files changed, 56 insertions(+), 12 deletions(-)

-- 
2.16.2

Re: [PATCH 2/2] git-svn: allow empty email-address in authors-prog and authors-file

[Andreas Heiduk]

Am 05.03.2018 um 10:37 schrieb Andreas Heiduk:
> 2018-03-05 2:42 GMT+01:00 Eric Sunshine <sunsh...@sunshineco.com>:
>> On Sun, Mar 4, 2018 at 6:22 AM, Andreas Heiduk <ashei...@gmail.com> wrote:
>>> ---
>>> diff --git a/perl/Git/SVN.pm b/perl/Git/SVN.pm
>>> @@ -1482,7 +1482,6 @@ sub call_authors_prog {
>>> }
>>> if ($author =~ /^\s*(.+?)\s*<(.*)>\s*$/) {
>>> my ($name, $email) = ($1, $2);
>>> -   $email = undef if length $2 == 0;
>>> return [$name, $email];
>>
>> Mental note: existing behavior intentionally makes $email undefined if
>> not present in $author; revised behavior leaves it defined.
> 
> But only if the data comes from authors-prog. authors-file is unaffected.
> 
>>
>>> } else {
>>> die "Author: $orig_author: $::_authors_prog returned "
>>> @@ -2020,8 +2019,8 @@ sub make_log_entry {
>>> remove_username($full_url);
>>> $log_entry{metadata} = "$full_url\@$r $uuid";
>>> $log_entry{svm_revision} = $r;
>>> -   $email ||= "$author\@$uuid";
>>> -   $commit_email ||= "$author\@$uuid";
>>> +   $email //= "$author\@$uuid";
>>> +   $commit_email //= "$author\@$uuid";
>>
>> With the revised behavior (above), $email is unconditionally defined,
>> so these //= expressions will _never_ assign "$author\@$uuid" to
>> $email. Am I reading that correctly? If so, then isn't this now just
>> dead code? Wouldn't it be clearer to remove these lines altogether?
> 
> The olf behaviour still kicks in if
>  - neither authors-file nor authors-prog is used
>  - only authors-file is used
> 
>> I see from reading the code that there is a "if (!defined $email)"
>> earlier in the function which becomes misleading with this change. I'd
>> have expected the patch to modify that, as well.
> 
> I will look into that one later.

I don't want to let that slip through the cracks: The `if` statement
still makes a difference if:

 - neither ` --authors-prog` nor `--authors-file` is active,
 - but `--use-log-author` is active and
 - the commit at hand does not contain a `From:` or `Signed-off-by:`
   trailer.

In that case the result was and still is `$user <$user>` for the author
and `$user <$user@$uuid>` for the comitter. That doesn't make sense to
me but doesn't concern me right now.

Re: [PATCH 1/2] git-svn: search --authors-prog in PATH too

[Andreas Heiduk]

Am 05.03.2018 um 20:48 schrieb Andreas Heiduk:
> Am 05.03.2018 um 18:52 schrieb Eric Wong:
>> Thanks both, I've queued 1/2 up with Eric S's edits at svn/authors-prog.
>> I'm not yet convinced 2/2 is a good change, however.
> 
> I'm not sure which direction your argument points to: Do you object to a
> $PATH search at all? Or would you like to remove the legacy code too?
> Or is the code/doc/... in bad shape?

OK, I've mismatched your reply and the patch number. So my new questions
are:

Do you object to the feature as such? Or would you like to remove the
legacy code too? Or is the code/doc/... in bad shape beyond what E.S.
already mentioned?

Right now my team performs a hefty "git filter-branch" after each "git
svn fetch" followed by black magic to set the new object ids in the
caches / rev-maps of git-svn. Official support for "no synthetic email"
would be much easier.

Re: [PATCH 1/2] git-svn: search --authors-prog in PATH too

[Andreas Heiduk]

Am 05.03.2018 um 18:52 schrieb Eric Wong:
> 
> Thanks both, I've queued 1/2 up with Eric S's edits at svn/authors-prog.
> I'm not yet convinced 2/2 is a good change, however.

I'm not sure which direction your argument points to: Do you object to a
$PATH search at all? Or would you like to remove the legacy code too?
Or is the code/doc/... in bad shape?

Re: [PATCH 2/2] git-svn: allow empty email-address in authors-prog and authors-file

[Andreas Heiduk]

2018-03-05 2:42 GMT+01:00 Eric Sunshine <sunsh...@sunshineco.com>:
> On Sun, Mar 4, 2018 at 6:22 AM, Andreas Heiduk <ashei...@gmail.com> wrote:
>> The email address in --authors-file and --authors-prog can be empty but
>> git-svn translated it into a syntethic email address in the form
>> $USERNAME@$REPO_UUID. Now git-svn behaves like git-commit: If the email
>> is explicitly set to the empty string, the commit does not contain
>> an email address.
>
> Falling back to "$name@$uuid" was clearly an intentional choice, so
> this seems like a rather significant change of behavior. How likely is
> it that users or scripts relying upon the existing behavior will break
> with this change? If the likelihood is high, should this behavior be
> opt-in?

I don't know nor understand the intial choice. Didn' git-commit support
empty emails once upon a time? Or is the SVN-UID important for some
SVK/SVM workflows?

My reasoning was: If authors-prog is NOT used, the behaviour
is unchanged - the UUID will be generated. If a Script IS used, then I
assume that a valid email was generated and this change will not
break these scripts. Only scripts intentionally not generating emails
will break. But again - was would be the purpose of such a script?
And such a script can be easily changed to add the UUID again.

So I think adding an explicit opt-in does not pay off.


> Doesn't such a behavior change deserve being documented (and possibly tests)?

The old behaviour was neither documented nor tested - the
change did not break any test after all.

>
>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>> ---
>> diff --git a/perl/Git/SVN.pm b/perl/Git/SVN.pm
>> @@ -1482,7 +1482,6 @@ sub call_authors_prog {
>> }
>> if ($author =~ /^\s*(.+?)\s*<(.*)>\s*$/) {
>> my ($name, $email) = ($1, $2);
>> -   $email = undef if length $2 == 0;
>> return [$name, $email];
>
> Mental note: existing behavior intentionally makes $email undefined if
> not present in $author; revised behavior leaves it defined.

But only if the data comes from authors-prog. authors-file is unaffected.

>
>> } else {
>> die "Author: $orig_author: $::_authors_prog returned "
>> @@ -2020,8 +2019,8 @@ sub make_log_entry {
>> remove_username($full_url);
>> $log_entry{metadata} = "$full_url\@$r $uuid";
>> $log_entry{svm_revision} = $r;
>> -   $email ||= "$author\@$uuid";
>> -   $commit_email ||= "$author\@$uuid";
>> +   $email //= "$author\@$uuid";
>> +   $commit_email //= "$author\@$uuid";
>
> With the revised behavior (above), $email is unconditionally defined,
> so these //= expressions will _never_ assign "$author\@$uuid" to
> $email. Am I reading that correctly? If so, then isn't this now just
> dead code? Wouldn't it be clearer to remove these lines altogether?

The olf behaviour still kicks in if
 - neither authors-file nor authors-prog is used
 - only authors-file is used

> I see from reading the code that there is a "if (!defined $email)"
> earlier in the function which becomes misleading with this change. I'd
> have expected the patch to modify that, as well.

I will look into that one later.

> Also, the Perl codebase in this project is still at 5.8, whereas the
> // operator (and //=) didn't become available until Perl 5.10.

I can expand these into something like

$email = defined $email ? $email : "$author\@$uuid";

or

$email = "$author\@$uuid" unless defined $email;


> (However, there has lately been some talk[1] about bumping the minimum
> Perl version to 5.10.)
>
> [1]: https://public-inbox.org/git/20171223174400.26668-1-ava...@gmail.com/

Did the thread result in some actual action?


>> } elsif ($self->use_svnsync_props) {
>> my $full_url = canonicalize_url(
>> add_path_to_url( $self->svnsync->{url}, $self->path )
>> @@ -2029,15 +2028,15 @@ sub make_log_entry {
>> remove_username($full_url);
>> my $uuid = $self->svnsync->{uuid};
>> $log_entry{metadata} = "$full_url\@$rev $uuid";
>> -   $email ||= "$author\@$uuid";
>> -   $commit_email ||= "$author\@$uuid";
>> +   $email //= "$author\@$uuid";
>> +   $commit_email //= "$author\@$uuid";
>> } else {
>> my $url = $self->metadata_url;
>> remove_username($url);
>> my $uuid = $self->rewrite_uuid || $self->ra->get_uuid;
>> $log_entry{metadata} = "$url\@$rev " . $uuid;
>> -   $email ||= "$author\@" . $uuid;
>> -   $commit_email ||= "$author\@" . $uuid;
>> +   $email //= "$author\@" . $uuid;
>> +   $commit_email //= "$author\@" . $uuid;
>> }
>> $log_entry{name} = $name;
>> $log_entry{email} = $email;

[PATCH 1/2] git-svn: search --authors-prog in PATH too

[Andreas Heiduk]

In 36db1eddf9 ("git-svn: add --authors-prog option", 2009-05-14) the path
to authors-prog was made absolute because git-svn changes the current
directoy in some situations. This makes sense if the program is part of
the repository but prevents searching via $PATH.

The old behaviour is still retained, but if the file does not exists, then
authors-prog is search in $PATH as any other command.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-svn.txt | 5 +
 git-svn.perl  | 3 ++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 636e09048e..b858374649 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -657,6 +657,11 @@ config key: svn.authorsfile
expected to return a single line of the form "Name ",
which will be treated as if included in the authors file.
 +
+Due to historical reasons a relative 'filename' is first searched
+relative to the current directory for 'init' and 'clone' and relative
+to the root of the working tree for 'fetch'. If 'filename' is
+not found, it is searched like any other command in '$PATH'.
++
 [verse]
 config key: svn.authorsProg
 
diff --git a/git-svn.perl b/git-svn.perl
index a6b6c3e40c..050f2a36f4 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -374,7 +374,8 @@ version() if $_version;
 usage(1) unless defined $cmd;
 load_authors() if $_authors;
 if (defined $_authors_prog) {
-   $_authors_prog = "'" . File::Spec->rel2abs($_authors_prog) . "'";
+   my $abs_file = File::Spec->rel2abs($_authors_prog);
+   $_authors_prog = "'" . $abs_file . "'" if -x $abs_file;
 }
 
 unless ($cmd =~ /^(?:clone|init|multi-init|commit-diff)$/) {
-- 
2.16.2

[PATCH 2/2] git-svn: allow empty email-address in authors-prog and authors-file

[Andreas Heiduk]

The email address in --authors-file and --authors-prog can be empty but
git-svn translated it into a syntethic email address in the form
$USERNAME@$REPO_UUID. Now git-svn behaves like git-commit: If the email
is explicitly set to the empty string, the commit does not contain
an email address.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 perl/Git/SVN.pm | 13 ++---
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/perl/Git/SVN.pm b/perl/Git/SVN.pm
index bc4eed3d75..b0a340b294 100644
--- a/perl/Git/SVN.pm
+++ b/perl/Git/SVN.pm
@@ -1482,7 +1482,6 @@ sub call_authors_prog {
}
if ($author =~ /^\s*(.+?)\s*<(.*)>\s*$/) {
my ($name, $email) = ($1, $2);
-   $email = undef if length $2 == 0;
return [$name, $email];
} else {
die "Author: $orig_author: $::_authors_prog returned "
@@ -2020,8 +2019,8 @@ sub make_log_entry {
remove_username($full_url);
$log_entry{metadata} = "$full_url\@$r $uuid";
$log_entry{svm_revision} = $r;
-   $email ||= "$author\@$uuid";
-   $commit_email ||= "$author\@$uuid";
+   $email //= "$author\@$uuid";
+   $commit_email //= "$author\@$uuid";
} elsif ($self->use_svnsync_props) {
my $full_url = canonicalize_url(
add_path_to_url( $self->svnsync->{url}, $self->path )
@@ -2029,15 +2028,15 @@ sub make_log_entry {
remove_username($full_url);
my $uuid = $self->svnsync->{uuid};
$log_entry{metadata} = "$full_url\@$rev $uuid";
-   $email ||= "$author\@$uuid";
-   $commit_email ||= "$author\@$uuid";
+   $email //= "$author\@$uuid";
+   $commit_email //= "$author\@$uuid";
} else {
my $url = $self->metadata_url;
remove_username($url);
my $uuid = $self->rewrite_uuid || $self->ra->get_uuid;
$log_entry{metadata} = "$url\@$rev " . $uuid;
-   $email ||= "$author\@" . $uuid;
-   $commit_email ||= "$author\@" . $uuid;
+   $email //= "$author\@" . $uuid;
+   $commit_email //= "$author\@" . $uuid;
}
$log_entry{name} = $name;
$log_entry{email} = $email;
-- 
2.16.2

Re: Git config multiple values

[Andreas Heiduk]

Hi,

Am 06.10.2017 um 19:25 schrieb Jonathan Nieder:
> Hi,
> 
> Jeff King wrote:
>> On Fri, Oct 06, 2017 at 01:10:17PM +0200, aleksander.baranowski wrote:
> 
>>> It's just an opinion, but this behaviour is no consistent for me.
>>>
>>> If it's not the bug it's a feature just let me know.
>>
>> It's a feature, though I agree that git-config is rather baroque. We're
>> mostly stuck with it for reasons of backwards compatibility, though.
> 
> This feels like a dodge.  Can we make a list of what is baroque here,
> with an eye to fixing it?  E.g. if we introduce a new --set option,
> then what should its semantics be, to be more intuitive?


My reading of the manual for 

git config --global user.name Foo2 Bar

is this:

   Multiple lines can be added to an option by using the --add option.

Does not apply here - no `--add` option, so no new value should be added.

   If you want to update or unset an option which can occur on multiple
   lines, a POSIX regexp value_regex needs to be given. 

does not apply: First: no "--unset" variant is used here leaving only "update".
Second: before that command there is only one value.

   Only the existing values that match the regexp are updated or unset.

Since "Two" does not match the previous value and `update` is the only 
described case left I'd expect that the command changes nothing.I don't
understand how the description allows `git config` to add a new value,
because the manual talks about "update" twice, nothing about adding.


Confused
--Andreas

Re: [PATCH] doc: correct command formatting

[Andreas Heiduk]

Am 28.09.2017 um 21:34 schrieb Jonathan Nieder:
> Andreas Heiduk wrote:
> 
>> +1, Thanks for spotting.
> 
> Thanks for looking it over.  Can we add your Reviewed-by?  (See [1]
> for what this means.)

Well, I'd like to see the following occurrence of the same problem
solved in that patch, too. Beyond that - your welcome.

>>
>> Documentation/git-format-patch.txt:  `--subject-prefix` option) has ` v` 
>> appended to it.  E.g.
>>
>> But here the space IS relevant but asciidoc does not pick up
>> the formatting. Perhaps that one could read like this:
>>
>>  `--subject-prefix` option) has `v` appended to it.  E.g.

...

> In some output formats, the text with backticks surrounding it is
> shown in a different background color, which makes something like
> `{space}v` tempting (with appropriate definition of {space} in
> the attributes section of asciidoc.conf).  But that feels way too
> subtle.
> 
> How about something like
> 
>   has a space and `v` appended to it

Well, in the original text "" is already used as a replacement
marker. Therefore "" seemed obvious to me as another replacement
marker which avoids exactly that problem.

> 
> ?
> 
> Thanks,
> Jonathan
> 
> [1] 
> https://kernel.googlesource.com/pub/scm/linux/kernel/git/torvalds/linux/+/9cd6681cb1169e815c41af0265165dd1b872f228/Documentation/process/submitting-patches.rst#563
> 

Re: [PATCH] doc: correct command formatting

[Andreas Heiduk]

Am 28.09.2017 um 16:06 schrieb Adam Dinwoodie:
> Leaving spaces around the `-delimeters for commands means asciidoc fails
> to parse them as the start of a literal string.  Remove an extraneous
> space that is causing a literal to not be formatted as such.
> 
> Signed-off-by: Adam Dinwoodie 
> ---
>  Documentation/git.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 6e3a6767e..98b9b46b9 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -75,7 +75,7 @@ example the following invocations are equivalent:
>  Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
>  `foo.bar` to the boolean true value (just like `[foo]bar` would in a
>  config file). Including the equals but with an empty value (like `git -c
> -foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
> +foo.bar= ...`) sets `foo.bar` to the empty string which `git config
>  --bool` will convert to `false`.
>  
>  --exec-path[=]::
> 

+1, Thanks for spotting.

I did a quick

grep -r " ` "

which came up with with another relevant place:

Documentation/git-format-patch.txt: `--subject-prefix` option) has ` v` 
appended to it.  E.g.

But here the space IS relevant but asciidoc does not pick up
the formatting. Perhaps that one could read like this:


`--subject-prefix` option) has `v` appended to it.  E.g.

Re: Commit dropped when swapping commits with rebase -i -p

[Andreas Heiduk]

Am 15.09.2017 um 22:52 schrieb Junio C Hamano:
> Sebastian Schuberth  writes:
>>
>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
>> index 6805a74aec..ccd0a04d54 100644
>> --- a/Documentation/git-rebase.txt
>> +++ b/Documentation/git-rebase.txt
>> @@ -782,10 +782,11 @@ case" recovery too!
>>  
>>  BUGS
>>  
>> -The todo list presented by `--preserve-merges --interactive` does not
>> -represent the topology of the revision graph.  Editing commits and
>> -rewording their commit messages should work fine, but attempts to
>> -reorder commits tend to produce counterintuitive results.
>> +Be careful when combining the `-i` / `--interactive` and `-p` /

"Be careful" is not necessary because the text is already in the "BUGS"
section.

>> +`--preserve-merges` options.  Reordering commits will drop commits from the
>> +main line. This is because the todo list does not represent the topology of 
>> the
>> +revision graph in this case.  However, editing commits and rewording their
>> +commit messages 'should' work fine.
>>  
>>  For example, an attempt to rearrange
>>  
> 
> 
> Anybody?  I personally feel that the updated text is not all that
> stronger but it is clearer by clarifying what "counterintuitive
> results" actually mean, but I am not the target audience this
> paragraph is trying to help, nor I am the one who is making excuse
> for a known bug, so...
> 

For me the proposed wording implies that the only bad effect are dropped
commits on the mainline. But I experienced something like this:


O--O--O--O---M--O==>   O--O--O--O---M--O
 \  /   \  /
  O--X--O--O O--X O


Where X was a commit without a ref and hence lost. Also the merge commit
seemed to combine two unrelated histories.

Therefore I would avoid "definitive wording" like "will drop" and use
vague wording along "there are various dragons out there" like this:

The todo list presented by `--preserve-merges --interactive` does
not represent the topology of the revision graph.  Editing
commits and rewording their commit messages should work fine.
But reordering, combining or dropping commits of a complex topology
can produce unexpected and useless results like missing commits,
wrong merges, merges combining two unrelated histories and
similar things.

Re: git-svn: Handling of branches created from subfolders

[Andreas Heiduk]

Am 19.08.2017 um 14:45 schrieb Jan Teske:
> Is there any way to fix such branches from subfolders in a way that they 
> integrate correctly with the converted git repository, without losing any (or 
> at least too much) history? If this is not possible with git-svn directly, 
> maybe I could prepare the SVN repo or post-process the converted git 
> repository somehow?

You can use `git replace --graft` to connect the first commit of the
loose branches with their source. After all connections are in place you
can use `git filter-branch` to make the replacements permanent.

This will not change the content or directory structure of branch1 or
branch2 but the diff with their parent commits will show up as a huge
delete/rename operation. So merging/Cherry-picking between trunk and
branch1/branch2 will be ... challenging.

Re: git svn show-externals output format

[Andreas Heiduk]

Am 19.08.2017 um 10:24 schrieb Alexander Groß:

> $ git svn show-externals
> 
> # /trunk/
> /trunk/https://svn.code.sf.net/p/gc-webdav/svn webdav
> /trunk/https://svn.code.sf.net/p/gc-webdav/svn@1 webdav-at-revision

This is the (bugged) output of `git svn show-externals` for "new
style" svn:externals.

> 
> # /trunk/sub directory/
> /trunk/sub directory/https://svn.code.sf.net/p/gc-webdav/svn 'webdav in 
> subdir'
> 
> An earlier version contains just one external:
> 
> $ git svn show-externals --revision 8
> 
> # /trunk/
> /trunk/webdav https://svn.code.sf.net/p/gc-webdav/svn/

And that the proper output for "old style" svn:externals.

> It seems like the output is inconsistent. [...]

SVN changed/extended the svn:externals format in version 1.5.
(See [1] for details). One thing is - they switched the
order of the arguments. `git svn` dit not pick up these changes
and hence interprets the new format incorrectly. See [2] for 
a similar discussion - it is from 2012!

> This makes consuming the output of git svn show-externals in HEAD
> difficult because the parts are not clearly separated by space and
> sometimes the path is the first element, sometimes it's a combination
> of first and last elements.

My practical solution was to skip the man in the middle and ask the SVN
server directly for the property values with something like that:

svn propget svn:externals -r 42 http://my-repo-url/path/to/ext/dir

I used the output to hardcode the values during the conversion.



[1] http://svnbook.red-bean.com/en/1.8/svn.advanced.externals.html
[2] 
https://public-inbox.org/git/e59cce45-6f92-4748-9b6e-2a5626479...@nikolaus-demmel.de/

Re: [PATCH] fix revisions doc about quoting for ':/' notation

[Andreas Heiduk]

Am 16.08.2017 um 05:21 schrieb ryenus:
> To make sure the `` in `:/` is seen as one search string,
> one should quote/escape `` properly.
> 
> Especially, the example given in the manual `:/fix nasty bug` does not
> work because of missing quotes. The examples are now corrected, and a
> note about quoting/escaping is added as well.

Right now the documentation describes the syntax as git sees the
parameters. This is agnostic of the shell or other UI with their
different quoting rules.  For example users of fish must quote
`rev@{2}`. A GUI might require no quoting at all. In that case `:/"fix
nasty bugs"` would be given to git verbatim and hence not find the revision.

Also: Other examples like `HEAD@{5 minutes ago}` need the same quoting.

So my suggestion is to not use quoting in the examples and provide only
a hint in the text. Example:

 {caret}{/}', e.g. 'HEAD^{/fix nasty bug}'::
A suffix '{caret}' to a revision parameter, followed by a brace
pair that contains a text led by a slash,
is the same as the ':/fix nasty bug' syntax below except that
it returns the youngest matching commit which is reachable from
the '' before '{caret}'.
+   Depending on the given text the shell's word splitting rules
+   might require additional quoting.

[PATCH v2] doc: clarify "config --bool" behaviour with empty values

[Andreas Heiduk]

`git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
`false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
t1300-repo-config.sh since 09bc098c2.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/config.txt | 10 +-
 Documentation/git.txt|  3 ++-
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab..478b9431e 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -216,15 +216,15 @@ boolean::
synonyms are accepted for 'true' and 'false'; these are all
case-insensitive.
 
-   true;; Boolean true can be spelled as `yes`, `on`, `true`,
-   or `1`.  Also, a variable defined without `= `
+   true;; Boolean true literals are `yes`, `on`, `true`,
+   and `1`.  Also, a variable defined without `= `
is taken as true.
 
-   false;; Boolean false can be spelled as `no`, `off`,
-   `false`, or `0`.
+   false;; Boolean false literals are `no`, `off`, `false`,
+   `0` and the empty string.
 +
 When converting value to the canonical form using `--bool` type
-specifier; 'git config' will ensure that the output is "true" or
+specifier, 'git config' will ensure that the output is "true" or
 "false" (spelled in lowercase).
 
 integer::
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 7dd5e0328..6e3a6767e 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -75,7 +75,8 @@ example the following invocations are equivalent:
 Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
 `foo.bar` to the boolean true value (just like `[foo]bar` would in a
 config file). Including the equals but with an empty value (like `git -c
-foo.bar= ...`) sets `foo.bar` to the empty string.
+foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
+--bool` will convert to `false`.
 
 --exec-path[=]::
Path to wherever your core Git programs are installed.
-- 
2.14.1

Re: [PATCH] doc: clarify "config --bool" behaviour with empty values

[Andreas Heiduk]

Am 14.08.2017 um 19:53 schrieb Junio C Hamano:
> Andreas Heiduk <ashei...@gmail.com> writes:
> 
>> `git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
>> `false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
>> t1300-repo-config.sh since 09bc098c2.
>>
>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>> ---
>>  Documentation/config.txt | 3 ++-
>>  Documentation/git.txt| 3 ++-
>>  2 files changed, 4 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index d5c9c4cab..d3261006b 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -221,7 +221,8 @@ boolean::
>>  is taken as true.
>>  
>> false;; Boolean false can be spelled as `no`, `off`,
>> -`false`, or `0`.
>> +`false`, `0`, no value (but still with `=`) or the
>> +empty string.
> 
[...]
 
> However, I think this "no value (but still with '=')" is making it
> more confusing than necessary for two reasons.
[...]
 
> I notice that in this Values section (where the boolean:: is the
> first entry) there is no mention on how to spell a string value.

I assumed this is due to the pretext of the definition list:

Values of many variables are treated as a simple string, but there
are variables that take values of specific types and there are rules
as to how to spell them.

After that I would NOT expect string values to be "specific". Also: If string 
values are explained here in the "Values" section, the line-breaking and escape 
sequences syntax should be here too.

So my (minimal) suggestion is:

   false;; Boolean false literals are `no`, `off`,
`false`, `0` and the empty string.

I'll adapt `true` in the same style and resend a patch.

[PATCH] doc: clarify "config --bool" behaviour with empty values

[Andreas Heiduk]

`git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
`false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
t1300-repo-config.sh since 09bc098c2.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/config.txt | 3 ++-
 Documentation/git.txt| 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab..d3261006b 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -221,7 +221,8 @@ boolean::
is taken as true.
 
false;; Boolean false can be spelled as `no`, `off`,
-   `false`, or `0`.
+   `false`, `0`, no value (but still with `=`) or the
+   empty string.
 +
 When converting value to the canonical form using `--bool` type
 specifier; 'git config' will ensure that the output is "true" or
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 7dd5e0328..6e3a6767e 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -75,7 +75,8 @@ example the following invocations are equivalent:
 Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
 `foo.bar` to the boolean true value (just like `[foo]bar` would in a
 config file). Including the equals but with an empty value (like `git -c
-foo.bar= ...`) sets `foo.bar` to the empty string.
+foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
+--bool` will convert to `false`.
 
 --exec-path[=]::
Path to wherever your core Git programs are installed.
-- 
2.13.3

[PATCH] doc: remove unsupported parameter from patch-id

[Andreas Heiduk]

The patch is read from standard input and not from a parameter.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-patch-id.txt | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
index cf71fba1c..442caff8a 100644
--- a/Documentation/git-patch-id.txt
+++ b/Documentation/git-patch-id.txt
@@ -56,9 +56,6 @@ OPTIONS
 
This is the default.
 
-::
-   The diff to create the ID of.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.13.3

[PATCH v2] doc: add missing values "none" and "default" for diff.wsErrorHighlight

[Andreas Heiduk]

The values have eluded documentation so far. While at it streamline
the wording by grouping relevant parts together.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/diff-config.txt  | 11 +++
 Documentation/diff-options.txt | 17 -
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index cbce8ec63..5ca942ab5 100644
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -200,7 +200,10 @@ diff.algorithm::
 +
 
 diff.wsErrorHighlight::
-   A comma separated list of `old`, `new`, `context`, that
-   specifies how whitespace errors on lines are highlighted
-   with `color.diff.whitespace`.  Can be overridden by the
-   command line option `--ws-error-highlight=`
+   Highlight whitespace errors in the `context`, `old` or `new`
+   lines of the diff.  Multiple values are separated by comma,
+   `none` resets previous values, `default` reset the list to
+   `new` and `all` is a shorthand for `old,new,context`.  The
+   whitespace errors are colored with `color.diff.whitespace`.
+   The command line option `--ws-error-highlight=`
+   overrides this setting.
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 89cc0f48d..d60f61ad4 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -300,15 +300,14 @@ ifndef::git-format-patch[]
with --exit-code.
 
 --ws-error-highlight=::
-   Highlight whitespace errors on lines specified by 
-   in the color specified by `color.diff.whitespace`.  
-   is a comma separated list of `old`, `new`, `context`.  When
-   this option is not given, only whitespace errors in `new`
-   lines are highlighted.  E.g. `--ws-error-highlight=new,old`
-   highlights whitespace errors on both deleted and added lines.
-   `all` can be used as a short-hand for `old,new,context`.
-   The `diff.wsErrorHighlight` configuration variable can be
-   used to specify the default behaviour.
+   Highlight whitespace errors in the `context`, `old` or `new`
+   lines of the diff.  Multiple values are separated by comma,
+   `none` resets previous values, `default` reset the list to
+   `new` and `all` is a shorthand for `old,new,context`.  When
+   this option is not given, and the configuration variable
+   `diff.wsErrorHighlight` is not set, only whitespace errors in
+   `new` lines are highlighted. The whitespace errors are colored
+   whith `color.diff.whitespace`.
 
 endif::git-format-patch[]
 
-- 
2.13.3

[PATCH] doc: add missing "none" value for diff.wsErrorHighlight

[Andreas Heiduk]

The value has not eluded documentation so far.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/diff-config.txt  | 2 +-
 Documentation/diff-options.txt | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index cbce8ec63..c84ced8f6 100644
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -200,7 +200,7 @@ diff.algorithm::
 +
 
 diff.wsErrorHighlight::
-   A comma separated list of `old`, `new`, `context`, that
+   A comma separated list of `old`, `new`, `context` and `none`, that
specifies how whitespace errors on lines are highlighted
with `color.diff.whitespace`.  Can be overridden by the
command line option `--ws-error-highlight=`
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 89cc0f48d..903d68eb7 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -302,7 +302,7 @@ ifndef::git-format-patch[]
 --ws-error-highlight=::
Highlight whitespace errors on lines specified by 
in the color specified by `color.diff.whitespace`.  
-   is a comma separated list of `old`, `new`, `context`.  When
+   is a comma separated list of `old`, `new`, `context` and `none`.  When
this option is not given, only whitespace errors in `new`
lines are highlighted.  E.g. `--ws-error-highlight=new,old`
highlights whitespace errors on both deleted and added lines.
-- 
2.13.3

Re: Bug^Feature? fetch protects only current working tree branch

[Andreas Heiduk]

Am 24.07.2017 um 00:13 schrieb Junio C Hamano:
> Andreas Heiduk <andreas.hei...@mathema.de> writes:
> 
>> A `git fetch . origin/master:master` protects the currently checked out 
>> branch (HEAD) unless the `-u/--update-head-ok` is supplied. This avoids a
>> mismatch between the index and HEAD. BUT branches which are HEADs in other
>> working trees do not get that care - their state is silently screwed up.
>>
>> Is this intended behaviour or and just an oversight while implementing
>> `git worktree`?
> 
> The latter.  

Ok, so I can adjust some of my helper scripts to catch and forbid this case.

> [...]"git worktree" is an interesting feature and has
> potential to become useful in wider variety of workflows than it
> currently is, but end users should consider it still experimental as
> it still is with many such small rough edges like this one.
> 
> Patches to help improving the feature is of course very welcome.

Since the core of the check is in C, I'll pass on this one. I could
supply a patch adding this to the "BUGS" section of git-worktree(1)
though :-)

Bug^Feature? fetch protects only current working tree branch

[Andreas Heiduk]

A `git fetch . origin/master:master` protects the currently checked out 
branch (HEAD) unless the `-u/--update-head-ok` is supplied. This avoids a
mismatch between the index and HEAD. BUT branches which are HEADs in other
working trees do not get that care - their state is silently screwed up.

Is this intended behaviour or and just an oversight while implementing
`git worktree`?


Steps to reproduce

# setup

git clone -b master $SOMETHING xtemp
cd xtemp
git reset --hard HEAD~5 # pretend to be back some time
git worktree add ../xtemp-wt1
git worktree add ../xtemp-wt2

# test

git fetch . origin/master:master

fatal: Refusing to fetch into current branch refs/heads/master  of 
non-bare repository
fatal: The remote end hung up unexpectedly

# OK, current working tree is protected, try another one:

git fetch . origin/master:xtemp-wt1

From .
   b4d1278..6e7b60d  origin/master -> xtemp-wt1

cd ../xtemp-wt1
git status

# admire messed up working tree here

# The protection is really "current working tree", not "first/main working 
tree"!

git fetch . origin/master:master

From .
   b4d1278..6e7b60d  origin/master -> master

cd ../xtemp
git status

# now it's messed up here too

# Try with "--update-head-ok" but check first.

cd ../xtemp-wt2

git fetch . origin/master:xtemp-wt2

fatal: Refusing to fetch into current branch refs/heads/xtemp-wt2 of 
non-bare repository
fatal: The remote end hung up unexpectedly

git fetch --update-head-ok . origin/master:xtemp-wt2

From .
   b4d1278..6e7b60d  origin/master -> xtemp-wt2

[PATCH] doc: clarify syntax for %C(auto,...) in pretty formats

[Andreas Heiduk]

The change actually adds only 

(e.g. `%C(auto,red)`)

but reflowing the paragraph blows it up a little.

 8< 
The manual correctly describes the syntax with `auto,` but the
trailing `,` is hard to spot in a terminal.  The HTML format does not
have this problem.  Adding an example helps both worlds.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/pretty-formats.txt | 11 ++-
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 38040e95b..b03985101 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -174,11 +174,12 @@ endif::git-rev-list[]
 - '%Creset': reset color
 - '%C(...)': color specification, as described under Values in the
   "CONFIGURATION FILE" section of linkgit:git-config[1];
-  adding `auto,` at the beginning will emit color only when colors are
-  enabled for log output (by `color.diff`, `color.ui`, or `--color`, and
-  respecting the `auto` settings of the former if we are going to a
-  terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
-  on the next placeholders until the color is switched again.
+  adding `auto,` at the beginning (e.g. `%C(auto,red)`) will emit
+  color only when colors are enabled for log output (by `color.diff`,
+  `color.ui`, or `--color`, and respecting the `auto` settings of the
+  former if we are going to a terminal). `auto` alone (i.e.
+  `%C(auto)`) will turn on auto coloring on the next placeholders
+  until the color is switched again.
 - '%m': left (`<`), right (`>`) or boundary (`-`) mark
 - '%n': newline
 - '%%': a raw '%'
-- 
2.13.1

Re: Transform log message during migration svn -> git (using git-svn)

[Andreas Heiduk]

Am 20.06.2017 um 14:32 schrieb paul.mat...@s4m.com:
> Well this is a possibility, of course. Our problem is that our SVN
> repository contains about 220.000 revisions currently. As a colleague of
> mine said that the command you suggest might take about 4 seconds per
> revision, it would take about 10 days to do this for our whole repository.
> So of course it could save a lot of time generally if such operation could
> be done immediately during git-svn.

My data point is this: A "git filter branch" run with ~2000 revisions
took several hours on a Windows 7 box. That number seems to be roughly
the same as your number. A comparable run on a Linux box took only about
10 minutes.

So: If your benchmark was done on Windows you might do that also on Linux.

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Andreas Heiduk]

Am 15.06.2017 um 18:43 schrieb Junio C Hamano:
> Another thing that may regress that you did not mention is that we
> would lose a convenient way to _count_ proposed changes coming via
> submitGit (i.e. you can simply go to the pull-request page), so that
> the number can be compared with the number of proposed changes
> directly made on the mailing list, which would be a good way to
> gauge how submitGit service is helping our community.  But even for
> that, you'd need to go to the list to find the denominator
> (i.e. total number of changes proposed), and by the time you do
> that, counting the numerator (i.e. those come via submitGit) by
> finding the telltale sign submitGit leaves in its output among these
> denominator messages should be trivial.

This numbers can be aquired quite easily if submitGit adds a defined
trailer to the converted commit message like this:

Signed-off-by: Foo Bar 
Submit-git-id: url-or-id-of-pr

[PATCH] git-svn: document special options for commit-diff

[Andreas Heiduk]

Some options specific for `git svn commit-diff` where not documented
so far.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-svn.txt | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index fba0b4eec..aa2aeabb6 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -459,6 +459,21 @@ Any other arguments are passed directly to 'git log'
(URL) may be omitted if you are working from a 'git svn'-aware
repository (that has been `init`-ed with 'git svn').
The -r option is required for this.
++
+The commit message is supplied either directly with the `-m` or `-F`
+option, or indirectly from the tag or commit when the second tree-ish
+denotes such an object, or it is requested by invoking an editor (see
+`--edit` option below).
+
+-m ;;
+--message=;;
+   Use the given `msg` as the commit message. This option
+   disables the `--edit` option.
+
+-F ;;
+--file=;;
+   Take the commit message from the given file. This option
+   disables the `--edit` option.
 
 'info'::
Shows information about a file or directory similar to what
-- 
2.13.1

[PATCH v4] doc: do not use `rm .git/index` when normalizing line endings

[Andreas Heiduk]

When illustrating how to normalize the line endings, the
documentation in gitattributes tells the user to `rm .git/index`.

This is incorrect for two reasons:

 - Users shouldn't be instructed to mess around with the internal
   implementation of Git using raw file system tools like `rm`.

 - Within a submodule or an additional working tree `.git` is just a
   file containing a `gitdir: ` pointer into the real `.git`
   directory.  Therefore `rm .git/index` does not work.

The purpose of the `rm .git/index` instruction is to remove all entries
from the index without touching the working tree.  The way to do this
with Git is to use `read-tree --empty`.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Helped-by: Junio C Hamano <gits...@pobox.com>
Helped-by: Torsten Bögershausen <tbo...@web.de>
---
 Documentation/gitattributes.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 473648386..2a2d7e2a4 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -229,7 +229,7 @@ From a clean working directory:
 
 -
 $ echo "* text=auto" >.gitattributes
-$ rm .git/index # Remove the index to re-scan the working directory
+$ git read-tree --empty   # Clean index, force re-scan of working directory
 $ git add .
 $ git status# Show files that will be normalized
 $ git commit -m "Introduce end-of-line normalization"
-- 
2.13.0

[PATCH v3] doc: do not use `rm .git/index` when normalizing line endings

[Andreas Heiduk]

When illustrating how to normalize the line endings, the
documentation in gitattributes tells the user to `rm .git/index`.

This is incorrect for two reasons:

 - Users shouldn't be instructed to mess around with the internal
   implementation of Git using raw file system tools like `rm`.

 - Within a submodule or an additional working tree `.git` is just a
   file containing a `gitdir: ` pointer into the real `.git`
   directory.  Therefore `rm .git/index` does not work.

The purpose or `rm .git/index` instruction is to remove all entries
from the index without touching the working tree.  The way to do this
with Git is to use `read-tree --empty`.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Helped-by: Junio C Hamano <gits...@pobox.com>
Helped-by: Torsten Bögershausen <tbo...@web.de>
---
 Documentation/gitattributes.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 473648386..2a2d7e2a4 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -229,7 +229,7 @@ From a clean working directory:
 
 -
 $ echo "* text=auto" >.gitattributes
-$ rm .git/index # Remove the index to re-scan the working directory
+$ git read-tree --empty   # Clean index, force re-scan of working directory
 $ git add .
 $ git status# Show files that will be normalized
 $ git commit -m "Introduce end-of-line normalization"
-- 
2.13.0

Re: [PATCH v2] doc: fix location of index in worktree scenatio

[Andreas Heiduk]

Am 12.06.2017 um 12:03 schrieb Torsten Bögershausen:
> Thanks for working on this (and keeping me in cc)
> 
> The commit head line does not fully match my expactions:
> "doc: fix location of index in worktree scenatio"
> "doc:" is OK, but is the "location of index" fixed ?
> Actually something that includes the important stuff:
> 
> "doc"
> "fix"
> "normalize the line endings"
> "worktree scenatio"
> 
> could be more helpful.
> 
> How about this as a header for the commit:
> "doc: normalize the line endings in a worktree scenatio"

Well, my patch does not document nor enhance the documentation
about EOL normalization per se.


> On 10/06/17 19:38, Andreas Heiduk wrote:
>> When setting `.gitattributes` in a second worktree, a plain `rm
>> .git/index`
>> does not actually delete the index.
> This feels somewhat short. setting .gitattributes is (in general)
> independent of the index.
> In normalizing line endings case the user needs to do both, fix
> attribiutes, and re-read the work tree, discarding the index.
> 
> How about this:
> 
> When line endings are normalized in a second worktree, a plain `rm
> .git/index`
> does not actually delete the index.
> Fix a long standing bug in the documentaton and use "git read-tree
> --empty" instead-

Before `git worktree` the description was correct. So what about this
subject and body:


doc: fix location of index while normalizing EOLs

When line endings are normalized in a second worktree, a plain
`rm .git/index` does not actually delete the index. Fix the
documentation by using `git read-tree --empty` instead.

[PATCH v2] doc: fix location of index in worktree scenatio

[Andreas Heiduk]

When setting `.gitattributes` in a second worktree, a plain `rm .git/index`
does not actually delete the index.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
Helped-by: Junio C Hamano <gits...@pobox.com>
---
 Documentation/gitattributes.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 473648386..2a2d7e2a4 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -229,7 +229,7 @@ From a clean working directory:
 
 -
 $ echo "* text=auto" >.gitattributes
-$ rm .git/index # Remove the index to re-scan the working directory
+$ git read-tree --empty   # Clean index, force re-scan of working directory
 $ git add .
 $ git status# Show files that will be normalized
 $ git commit -m "Introduce end-of-line normalization"
-- 
2.13.0

Re: [PATCH] doc: fix location of index in worktree scenatio

[Andreas Heiduk]

Am 10.06.2017 um 13:17 schrieb Junio C Hamano:
> Andreas Heiduk <ashei...@gmail.com> writes:
> 
>> When setting `.gitattributes` in a second worktree, a plain `rm .git/index`
>> does not actually delete the index.
>>
[...]
> Right.  
> 
> I however have to wonder if we can do the same without futzing
> directly with the "index" file as a filesystem entity.  With or
> without your update, what is taught in the document feels like
> munging a disk block with binary editor to correct a corrupted
> filesystem X-<.

IMO `rm .git/index` is like munging a disk block WITHOUT a binary
editor but with plain `dd seek=... skip=... count=...`, `hexdump`,
`ed` and back - every step is clear in principle but painful and
dangerous. :-)

> For example, can we do this "empty the index" step with things like
> 
> $ git rm --cached .

That would be `git rm --cached -rq .`?

Executing this in the git repo gives me an index file with 2.1kb. I
don't know whether or not this index still contains something relevant
for this case.

> or
> 
> $ git read-tree --empty
> 
> instead?

Nice! The `index` file contains 46 bytes.

For me THAT one is like a nice binary editor apt for the job :-)
I'll queue that.

[PATCH] doc: fix location of index in worktree scenatio

[Andreas Heiduk]

When setting `.gitattributes` in a second worktree, a plain `rm .git/index`
does not actually delete the index.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/gitattributes.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 473648386..4c6b74fa6 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -229,7 +229,7 @@ From a clean working directory:
 
 -
 $ echo "* text=auto" >.gitattributes
-$ rm .git/index # Remove the index to re-scan the working directory
+$ rm "$(git rev-parse --git-path index)"  # Remove the index to re-scan the 
working directory
 $ git add .
 $ git status# Show files that will be normalized
 $ git commit -m "Introduce end-of-line normalization"
-- 
2.13.0

[PATCH v2 2/2] add [--] to usage of filter-branch

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 git-filter-branch.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/git-filter-branch.sh b/git-filter-branch.sh
index 2758ae5eb..3a74602ef 100755
--- a/git-filter-branch.sh
+++ b/git-filter-branch.sh
@@ -87,7 +87,7 @@ USAGE="[--setup ] [--env-filter ]
[--commit-filter ] [--tag-name-filter ]
[--subdirectory-filter ] [--original ]
[-d ] [-f | --force]
-   [...]"
+   [--] [...]"
 
 OPTIONS_SPEC=
 . git-sh-setup
-- 
2.13.0

[PATCH v2 1/2] add setup step to filter-branch

[Andreas Heiduk]

A specific `--setup` step in `git filter-branch` makes it much easier
to define the initial values of variables used in the real filters.
Also sourcing/defining utility functions here instead of
`--env-filter` improves performance and minimizes clogging the output
in case of errors.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-filter-branch.txt | 17 -
 git-filter-branch.sh| 18 +-
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-filter-branch.txt 
b/Documentation/git-filter-branch.txt
index 7b695dbb7..9e5169aa6 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -8,11 +8,11 @@ git-filter-branch - Rewrite branches
 SYNOPSIS
 
 [verse]
-'git filter-branch' [--env-filter ] [--tree-filter ]
-   [--index-filter ] [--parent-filter ]
-   [--msg-filter ] [--commit-filter ]
-   [--tag-name-filter ] [--subdirectory-filter ]
-   [--prune-empty]
+'git filter-branch' [--setup ] [--env-filter ]
+   [--tree-filter ] [--index-filter ]
+   [--parent-filter ] [--msg-filter ]
+   [--commit-filter ] [--tag-name-filter ]
+   [--subdirectory-filter ] [--prune-empty]
[--original ] [-d ] [-f | --force]
[--] [...]
 
@@ -82,6 +82,13 @@ multiple commits.
 OPTIONS
 ---
 
+--setup ::
+   This is not a real filter executed for each commit but a one
+   time setup just before the loop. Therefore no commit-specific
+   variables are defined yet.  Functions or variables defined here
+   can be used or modified in the following filter steps except
+   the commit filter, for technical reasons.
+
 --env-filter ::
This filter may be used if you only need to modify the environment
in which the commit will be performed.  Specifically, you might
diff --git a/git-filter-branch.sh b/git-filter-branch.sh
index aafaf708d..2758ae5eb 100755
--- a/git-filter-branch.sh
+++ b/git-filter-branch.sh
@@ -81,11 +81,12 @@ set_ident () {
finish_ident COMMITTER
 }
 
-USAGE="[--env-filter ] [--tree-filter ]
-   [--index-filter ] [--parent-filter ]
-   [--msg-filter ] [--commit-filter ]
-   [--tag-name-filter ] [--subdirectory-filter ]
-   [--original ] [-d ] [-f | --force]
+USAGE="[--setup ] [--env-filter ]
+   [--tree-filter ] [--index-filter ]
+   [--parent-filter ] [--msg-filter ]
+   [--commit-filter ] [--tag-name-filter ]
+   [--subdirectory-filter ] [--original ]
+   [-d ] [-f | --force]
[...]"
 
 OPTIONS_SPEC=
@@ -96,6 +97,7 @@ if [ "$(is_bare_repository)" = false ]; then
 fi
 
 tempdir=.git-rewrite
+filter_setup=
 filter_env=
 filter_tree=
 filter_index=
@@ -148,6 +150,9 @@ do
-d)
tempdir="$OPTARG"
;;
+   --setup)
+   filter_setup="$OPTARG"
+   ;;
--env-filter)
filter_env="$OPTARG"
;;
@@ -317,6 +322,9 @@ else
need_index=
 fi
 
+eval "$filter_setup" < /dev/null ||
+   die "filter setup failed: $filter_setup"
+
 while read commit parents; do
git_filter_branch__commit_count=$(($git_filter_branch__commit_count+1))
 
-- 
2.13.0

Re: [PATCH 2/2] add [--] to usage of filter-branch

[Andreas Heiduk]

Am 09.06.2017 um 15:14 schrieb Junio C Hamano:
> Andreas Heiduk <ashei...@gmail.com> writes:
> 
>> Am 03.06.2017 um 12:17 schrieb Andreas Heiduk:
>>> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
>>> ---
>>>  Documentation/git-filter-branch.txt | 3 ++-
>>>  git-filter-branch.sh| 2 +-
>>>  2 files changed, 3 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/Documentation/git-filter-branch.txt 
>>> b/Documentation/git-filter-branch.txt
>>> index 45c849d8c..1efdda804 100644
>>> --- a/Documentation/git-filter-branch.txt
>>> +++ b/Documentation/git-filter-branch.txt
>>> @@ -86,7 +86,8 @@ OPTIONS
>>> This is not a real filter executed for each commit but a one
>>> time setup just before the loop. Therefore no commit-specific
>>> variables are defined yet.  Functions or variables defined here
>>> -   can be used or modified in the following filter steps.
>>> +   can be used or modified in the following filter steps except
>>> +   the commit filter, for technical reasons.
>>
>> I'll move that into the previous commit.
> 
> Yeah, the description of "technical limitation" is different from
> clarifying the disambiguating "--" in the documentation.
> 
> I am curious what the "technical reason" really is, though ;-)
> 

Well, I just picked up the wording from the "Filter" section a 
couple paragraphs above:

> The filters are applied in the order as listed below.  The 
> argument is always evaluated in the shell context using the 'eval' command
> (with the notable exception of the commit filter, for technical reasons).

Because these reasons exist independently from my change I think I
can get away with just that snappy reference :-]

[PATCH] doc: describe git svn init --ignore-refs

[Andreas Heiduk]

Add the missing documentation for `git svn init --ignore-refs`.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-svn.txt | 16 
 1 file changed, 16 insertions(+)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 9bee9b0c4..fba0b4eec 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -95,6 +95,10 @@ If you still want the old default, you can get it by passing
 `--prefix ""` on the command line (`--prefix=""` may not work if
 your Perl's Getopt::Long is < v2.37).
 
+--ignore-refs=;;
+   When passed to 'init' or 'clone' this regular expression will
+   be preserved as a config key.  See 'fetch' for a description
+   of `--ignore-refs`.
 --ignore-paths=;;
When passed to 'init' or 'clone' this regular expression will
be preserved as a config key.  See 'fetch' for a description
@@ -138,6 +142,18 @@ the same local time zone.
 --parent;;
Fetch only from the SVN parent of the current HEAD.
 
+--ignore-refs=;;
+   Ignore refs for branches or tags matching the Perl regular
+   expression. A "negative look-ahead assertion" like
+   `^refs/remotes/origin/(?!tags/wanted-tag|wanted-branch).*$`
+   can be used to allow only certain refs.
++
+[verse]
+config key: svn-remote..ignore-refs
++
+If the ignore-refs configuration key is set, and the command-line
+option is also given, both regular expressions will be used.
+
 --ignore-paths=;;
This allows one to specify a Perl regular expression that will
cause skipping of all matching paths from checkout from SVN.
-- 
2.13.0

Re: [PATCH 2/2] add [--] to usage of filter-branch

[Andreas Heiduk]

Am 03.06.2017 um 12:17 schrieb Andreas Heiduk:
> Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
> ---
>  Documentation/git-filter-branch.txt | 3 ++-
>  git-filter-branch.sh| 2 +-
>  2 files changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-filter-branch.txt 
> b/Documentation/git-filter-branch.txt
> index 45c849d8c..1efdda804 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -86,7 +86,8 @@ OPTIONS
>   This is not a real filter executed for each commit but a one
>   time setup just before the loop. Therefore no commit-specific
>   variables are defined yet.  Functions or variables defined here
> - can be used or modified in the following filter steps.
> + can be used or modified in the following filter steps except
> + the commit filter, for technical reasons.

I'll move that into the previous commit.

[PATCH 1/2] add setup step to filter-branch

[Andreas Heiduk]

A specific `--setup` step in `git filter-branch` makes it much easier
to define the initial values of variables used in the real filters.
Also sourcing/defining utility functions here instead of
`--env-filter` improves performance and minimizes clogging the output
in case of errors.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-filter-branch.txt | 16 +++-
 git-filter-branch.sh| 18 +-
 2 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-filter-branch.txt 
b/Documentation/git-filter-branch.txt
index 6e4bb0220..45c849d8c 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -8,11 +8,11 @@ git-filter-branch - Rewrite branches
 SYNOPSIS
 
 [verse]
-'git filter-branch' [--env-filter ] [--tree-filter ]
-   [--index-filter ] [--parent-filter ]
-   [--msg-filter ] [--commit-filter ]
-   [--tag-name-filter ] [--subdirectory-filter ]
-   [--prune-empty]
+'git filter-branch' [--setup ] [--env-filter ]
+   [--tree-filter ] [--index-filter ]
+   [--parent-filter ] [--msg-filter ]
+   [--commit-filter ] [--tag-name-filter ]
+   [--subdirectory-filter ] [--prune-empty]
[--original ] [-d ] [-f | --force]
[--] [...]
 
@@ -82,6 +82,12 @@ multiple commits.
 OPTIONS
 ---
 
+--setup ::
+   This is not a real filter executed for each commit but a one
+   time setup just before the loop. Therefore no commit-specific
+   variables are defined yet.  Functions or variables defined here
+   can be used or modified in the following filter steps.
+
 --env-filter ::
This filter may be used if you only need to modify the environment
in which the commit will be performed.  Specifically, you might
diff --git a/git-filter-branch.sh b/git-filter-branch.sh
index aafaf708d..2758ae5eb 100755
--- a/git-filter-branch.sh
+++ b/git-filter-branch.sh
@@ -81,11 +81,12 @@ set_ident () {
finish_ident COMMITTER
 }
 
-USAGE="[--env-filter ] [--tree-filter ]
-   [--index-filter ] [--parent-filter ]
-   [--msg-filter ] [--commit-filter ]
-   [--tag-name-filter ] [--subdirectory-filter ]
-   [--original ] [-d ] [-f | --force]
+USAGE="[--setup ] [--env-filter ]
+   [--tree-filter ] [--index-filter ]
+   [--parent-filter ] [--msg-filter ]
+   [--commit-filter ] [--tag-name-filter ]
+   [--subdirectory-filter ] [--original ]
+   [-d ] [-f | --force]
[...]"
 
 OPTIONS_SPEC=
@@ -96,6 +97,7 @@ if [ "$(is_bare_repository)" = false ]; then
 fi
 
 tempdir=.git-rewrite
+filter_setup=
 filter_env=
 filter_tree=
 filter_index=
@@ -148,6 +150,9 @@ do
-d)
tempdir="$OPTARG"
;;
+   --setup)
+   filter_setup="$OPTARG"
+   ;;
--env-filter)
filter_env="$OPTARG"
;;
@@ -317,6 +322,9 @@ else
need_index=
 fi
 
+eval "$filter_setup" < /dev/null ||
+   die "filter setup failed: $filter_setup"
+
 while read commit parents; do
git_filter_branch__commit_count=$(($git_filter_branch__commit_count+1))
 
-- 
2.13.0

[PATCH 2/2] add [--] to usage of filter-branch

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-filter-branch.txt | 3 ++-
 git-filter-branch.sh| 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-filter-branch.txt 
b/Documentation/git-filter-branch.txt
index 45c849d8c..1efdda804 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -86,7 +86,8 @@ OPTIONS
This is not a real filter executed for each commit but a one
time setup just before the loop. Therefore no commit-specific
variables are defined yet.  Functions or variables defined here
-   can be used or modified in the following filter steps.
+   can be used or modified in the following filter steps except
+   the commit filter, for technical reasons.
 
 --env-filter ::
This filter may be used if you only need to modify the environment
diff --git a/git-filter-branch.sh b/git-filter-branch.sh
index 2758ae5eb..3a74602ef 100755
--- a/git-filter-branch.sh
+++ b/git-filter-branch.sh
@@ -87,7 +87,7 @@ USAGE="[--setup ] [--env-filter ]
[--commit-filter ] [--tag-name-filter ]
[--subdirectory-filter ] [--original ]
[-d ] [-f | --force]
-   [...]"
+   [--] [...]"
 
 OPTIONS_SPEC=
 . git-sh-setup
-- 
2.13.0

[PATCH v1] doc: rewrite description for rev-parse --short

[Andreas Heiduk]

`git rev-parse --short` is not a generic modifier but just a variant
of `--verify` and considers the given length only as a suggestion to
ensure uniqueness.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/config.txt|  1 +
 Documentation/git-rev-parse.txt | 12 ++--
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 43d830ee3..3256a3344 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -883,6 +883,7 @@ core.abbrev::
computed based on the approximate number of packed objects
in your repository, which hopefully is enough for
abbreviated object names to stay unique for some time.
+   The minimum length is 4.
 
 add.ignoreErrors::
 add.ignore-errors (deprecated)::
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index c40c47044..b1293f24b 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -126,6 +126,12 @@ can be used.
'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
the command input is still interpreted as usual.
 
+--short[=length]::
+   Same as `--verify` but shortens the object name to a unique
+   prefix with at least `length` characters. The minimum length
+   is 4, the default is the effective value of the `core.abbrev`
+   configuration variable (see linkgit:git-config[1]).
+
 --not::
When showing object names, prefix them with '{caret}' and
strip '{caret}' prefix from the object names that already have
@@ -136,12 +142,6 @@ can be used.
The option core.warnAmbiguousRefs is used to select the strict
abbreviation mode.
 
---short::
---short=number::
-   Instead of outputting the full SHA-1 values of object names try to
-   abbreviate them to a shorter unique name. When no length is specified
-   7 is used. The minimum length is 4.
-
 --symbolic::
Usually the object names are output in SHA-1 form (with
possible '{caret}' prefix); this option makes them output in a
-- 
2.13.0

Re: [PATCH] doc: Improve description for rev-parse --short

[Andreas Heiduk]

Am 30.05.2017 um 06:10 schrieb Junio C Hamano:
>>  --short=number::
>>  Instead of outputting the full SHA-1 values of object names try to
>>  abbreviate them to a shorter unique name. When no length is specified
>> -7 is used. The minimum length is 4.
>> +the effective value of the configuration variable `core.abbrev` (see
>> +linkgit:git-config[1]) is used.  The minimum length is 4.  The length
>> +may be exceeded to ensure unique object names.  Implies `--verify`.
> 
> "Implies --verify" is less important than the fact that multiple
> object names cannot be given from the end-users' (and readers')
> point of view, no?  The sentence in the pre-context still hints
> (incorrectly) that we might take multiple names---that would want to
> be corrected, no?
> 
> Let me try.
> 
> --short[=length]::
>   Take a single object name, and output a prefix of the object
>   name whose length is at least the specified length and
>   sufficient to ensure uniqueness of the name.  The minimum
>   length is 4.  When no length is given, the effective value
>   of the `core.abbrev` configuration variable is used.
> 
> Thanks.

Your are right about s/names/name/ in the pretext.

But I think that the link to the `--verify` option is still important.
The text there talks about when something is output, exit codes and
about `^{type}` peeling. Also `--quiet` is linked to
`--verify` and hence relevant here.

So I'd like to patch your text to this:

  --short[=length]::
Same as `--verify` but output only a prefix of the object
name whose length is at least the specified length and
sufficient to ensure uniqueness of the name.  The minimum
length is 4.  When no length is given, the effective value
of the `core.abbrev` configuration variable is used.

And I'd like to move the section up right to `--verify` and `--quiet`.
The options in this section are not sorted alphabetically anyways and
the relevant parts would be adjacent. Is that OK?

ALso: Did you remove the `linkgit` by intention or just by accident?

[PATCH] doc: Improve description for rev-parse --short

[Andreas Heiduk]

First: `git rev-parse --short` without a number does use a fixed default but
`core.abbrev` which in turn uses `find_unique_abbrev` internally.

Second: `--short` implies `--verify` since the beginning (d50125085a), so
it cannot be used for bulk-shortening ids unfortunately.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/config.txt| 1 +
 Documentation/git-rev-parse.txt | 4 +++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index e0b9fd0bc..158cb588b 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -862,6 +862,7 @@ core.abbrev::
computed based on the approximate number of packed objects
in your repository, which hopefully is enough for
abbreviated object names to stay unique for some time.
+   The minimum length is 4.
 
 add.ignoreErrors::
 add.ignore-errors (deprecated)::
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index c40c47044..7a7421c8e 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -140,7 +140,9 @@ can be used.
 --short=number::
Instead of outputting the full SHA-1 values of object names try to
abbreviate them to a shorter unique name. When no length is specified
-   7 is used. The minimum length is 4.
+   the effective value of the configuration variable `core.abbrev` (see
+   linkgit:git-config[1]) is used.  The minimum length is 4.  The length
+   may be exceeded to ensure unique object names.  Implies `--verify`.
 
 --symbolic::
Usually the object names are output in SHA-1 form (with
-- 
2.13.0

[PATCH] doc: filter-branch does not require re-export of vars

[Andreas Heiduk]

The function `set_ident` in `filter-branch` exported the variables
GIT_(AUTHOR|COMMITTER)_(NAME|EMAIL|DATE) at least since 6f6826c52b in 2007.
Therefore the filter scripts don't need to re-eport them again.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-filter-branch.txt | 5 +
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/Documentation/git-filter-branch.txt 
b/Documentation/git-filter-branch.txt
index 6e4bb0220..7b695dbb7 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -86,8 +86,7 @@ OPTIONS
This filter may be used if you only need to modify the environment
in which the commit will be performed.  Specifically, you might
want to rewrite the author/committer name/email/time environment
-   variables (see linkgit:git-commit-tree[1] for details).  Do not forget
-   to re-export the variables.
+   variables (see linkgit:git-commit-tree[1] for details).
 
 --tree-filter ::
This is the filter for rewriting the tree and its contents.
@@ -340,12 +339,10 @@ git filter-branch --env-filter '
if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
then
GIT_AUTHOR_EMAIL=j...@example.com
-   export GIT_AUTHOR_EMAIL
fi
if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
then
GIT_COMMITTER_EMAIL=j...@example.com
-   export GIT_COMMITTER_EMAIL
fi
 ' -- --all
 
-- 
2.13.0

[PATCH] Documentation: Fix formatting typo in pretty-formats.txt

[Andreas Heiduk]

A missing space messed up formatting of the `%(trailers)` format.
---
 Documentation/pretty-formats.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 47b286b33..38040e95b 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -199,7 +199,7 @@ endif::git-rev-list[]
   than given and there are spaces on its left, use those spaces
 - '%><()', '%><|()': similar to '% <()', '%<|()'
   respectively, but padding both sides (i.e. the text is centered)
--%(trailers): display the trailers of the body as interpreted by
+- %(trailers): display the trailers of the body as interpreted by
   linkgit:git-interpret-trailers[1]
 
 NOTE: Some placeholders may depend on other options given to the
-- 
2.13.0

[PATCH] Documentation: Fix reference to isExists for interpret-trailers

[Andreas Heiduk]

The manual for "git interpret-trailers" mentioned a non-existing
literal `overwrite` for its config option `trailer.ifexists`. Fixed
by using `replace` instead.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt 
b/Documentation/git-interpret-trailers.txt
index 09074c75a..31cdeaecd 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -123,7 +123,7 @@ trailer.ifexists::
same  in the message.
 +
 The valid values for this option are: `addIfDifferentNeighbor` (this
-is the default), `addIfDifferent`, `add`, `overwrite` or `doNothing`.
+is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
 +
 With `addIfDifferentNeighbor`, a new trailer will be added only if no
 trailer with the same (, ) pair is above or below the line
-- 
2.13.0

[PATCH v2] Docs: Add some missing options to git-diff.txt

[Andreas Heiduk]

New attempt due to whitespace fixes after EndOfSenctence.

Junio C Hamano writes:
> This is probably a shared issue with the original text for
> "diff-files", but I think we must stress that these options make
> sense only when you are in the middle of conflict resolution.  
>
> In addition, unlike "diff-files", if these were to appear in the
> general "git diff" documentation, it also must stress that these
> options are only about comparing the index and the working tree
> files, e.g. "git diff --ours HEAD^ HEAD" does not make sense.

Well, this wording picks up your points but I won't call it "stress
it" :-) However this should do the job.


--- 8< -- >8 -
git-diff understands "--ours", "--theirs" and "--base" for files with
conflicts. But so far they were not documented for the central diff
command but only for diff-files.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-diff.txt | 14 ++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index bbab35fca..b0c1bb95c 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -97,6 +97,20 @@ OPTIONS
 :git-diff: 1
 include::diff-options.txt[]
 
+-1 --base::
+-2 --ours::
+-3 --theirs::
+   Compare the working tree with the "base" version (stage #1),
+   "our branch" (stage #2) or "their branch" (stage #3).  The
+   index contains these stages only for unmerged entries i.e.
+   while resolving conflicts.  See linkgit:git-read-tree[1]
+   section "3-Way Merge" for detailed information.
+
+-0::
+   Omit diff output for unmerged entries and just show
+   "Unmerged".  Can be used only when comparing the working tree
+   with the index.
+
 ...::
The  parameters, when given, are used to limit
the diff to the named paths (you can give directory
-- 
2.12.2

[PATCH v1] Docs: Add some missing options to git-diff.txt

[Andreas Heiduk]

Well, this wording picks up your points but I won't call it "stress
it" :-) However this should do the job.

--8<-->8--
git-diff understands "--ours", "--theirs" and "--base" for files with
conflicts. But so far they were not documented for the central diff
command but only for diff-files.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-diff.txt | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index bbab35fca..2bccf4505 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -97,6 +97,21 @@ OPTIONS
 :git-diff: 1
 include::diff-options.txt[]
 
+-1 --base::
+-2 --ours::
+-3 --theirs::
+   Compare the working tree with the "base" version (stage #1),
+   "our branch" (stage #2) or "their branch" (stage #3). The
+   index contains these stages only for unmerged entries i.e.
+   while resolving conflicts.  See linkgit:git-read-tree[1]
+   section "3-Way Merge" for more information.
+
+-0::
+   Omit diff output for unmerged entries and just show
+   "Unmerged". Can be used only when comparing the working tree
+   with the index
+
+
 ...::
The  parameters, when given, are used to limit
the diff to the named paths (you can give directory
-- 
2.12.2

[PATCH] Docs: Add some missing options to git-diff.txt

[Andreas Heiduk]

git-diff understands "--ours", "--theirs" and "--base" for files with
conflicts. But so far they were not documented for the central diff
command but only for diff-files.

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/git-diff.txt | 8 
 1 file changed, 8 insertions(+)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index bbab35f..91ced4f 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -97,6 +97,14 @@ OPTIONS
 :git-diff: 1
 include::diff-options.txt[]
 
+-1 --base::
+-2 --ours::
+-3 --theirs::
+-0::
+   Diff against the "base" version, "our branch" or "their
+   branch" respectively. The option -0 can be given to omit diff
+   output for unmerged entries and just show "Unmerged".
+
 ...::
The  parameters, when given, are used to limit
the diff to the named paths (you can give directory
-- 
2.7.4

[PATCH v3] Documentation: Improve description for core.quotePath

[Andreas Heiduk]

Linking the description for pathname quoting to the configuration
variable "core.quotePath" removes inconstistent and incomplete
sections while also giving two hints how to deal with it: Either with
"-c core.quotePath=false" or with "-z".

Signed-off-by: Andreas Heiduk <ashei...@gmail.com>
---
 Documentation/config.txt  | 23 +--
 Documentation/diff-format.txt |  7 ---
 Documentation/diff-generate-patch.txt |  7 +++
 Documentation/diff-options.txt|  7 +++
 Documentation/git-apply.txt   |  7 +++
 Documentation/git-commit.txt  |  9 ++---
 Documentation/git-ls-files.txt| 10 ++
 Documentation/git-ls-tree.txt | 10 +++---
 Documentation/git-status.txt  |  7 +++
 9 files changed, 48 insertions(+), 39 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 015346c..23233d8 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -350,16 +350,19 @@ core.checkStat::
all fields, including the sub-second part of mtime and ctime.
 
 core.quotePath::
-   The commands that output paths (e.g. 'ls-files',
-   'diff'), when not given the `-z` option, will quote
-   "unusual" characters in the pathname by enclosing the
-   pathname in a double-quote pair and with backslashes the
-   same way strings in C source code are quoted.  If this
-   variable is set to false, the bytes higher than 0x80 are
-   not quoted but output as verbatim.  Note that double
-   quote, backslash and control characters are always
-   quoted without `-z` regardless of the setting of this
-   variable.
+   Commands that output paths (e.g. 'ls-files', 'diff'), will
+   quote "unusual" characters in the pathname by enclosing the
+   pathname in double-quotes and escaping those characters with
+   backslashes in the same way C escapes control characters (e.g.
+   `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
+   values larger than 0x80 (e.g. octal `\302\265` for "micro" in
+   UTF-8).  If this variable is set to false, bytes higher than
+   0x80 are not considered "unusual" any more. Double-quotes,
+   backslash and control characters are always escaped regardless
+   of the setting of this variable.  A simple space character is
+   not considered "unusual".  Many commands can output pathnames
+   completely verbatim using the `-z` option. The default value
+   is true.
 
 core.eol::
Sets the line ending type to use in the working directory for
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index cf52626..706916c 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -78,9 +78,10 @@ Example:
 :100644 100644 5be4a4.. 00.. M file.c
 
 
-When `-z` option is not used, TAB, LF, and backslash characters
-in pathnames are represented as `\t`, `\n`, and `\\`,
-respectively.
+Without the `-z` option, pathnames with "unusual" characters are
+quoted as explained for the configuration variable `core.quotePath`
+(see linkgit:git-config[1]).  Using `-z` the filename is output
+verbatim and the line is terminated by a NUL byte.
 
 diff format for merges
 --
diff --git a/Documentation/diff-generate-patch.txt 
b/Documentation/diff-generate-patch.txt
index d2a7ff5..231105c 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -53,10 +53,9 @@ The index line includes the SHA-1 checksum before and after 
the change.
 The  is included if the file mode does not change; otherwise,
 separate lines indicate the old and the new mode.
 
-3.  TAB, LF, double quote and backslash characters in pathnames
-are represented as `\t`, `\n`, `\"` and `\\`, respectively.
-If there is need for such substitution then the whole
-pathname is put in double quotes.
+3.  Pathnames with "unusual" characters are quoted as explained for
+the configuration variable `core.quotePath` (see
+linkgit:git-config[1]).
 
 4.  All the `file1` files in the output refer to files before the
 commit, and all the `file2` files refer to files after the commit.
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index d91ddbd..89cc0f4 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -192,10 +192,9 @@ ifndef::git-log[]
given, do not munge pathnames and use NULs as output field terminators.
 endif::git-log[]
 +
-Without this option, each pathname output will have TAB, LF, double quotes,
-and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`,
-respectively, and the pathname will be enclosed in double quotes if
-any of those replacements occurre