Re: [PATCH 5/8] git-format-patch.txt: general rewordings and cleanups
Stephen Boyd venit, vidit, dixit 23.04.2009 11:37:
Show 45 quoted lines
> Clarify --no-binary description using some words from the original
> commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix
> description. Add --thread style option to synopsis and reorganize it a
> bit. Clarify renaming patches example and the configuration paragraph.
>
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
> ---
> Documentation/git-format-patch.txt | 38 ++++++++++++++++++------------------
> 1 files changed, 19 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index 4a43c64..5ac9e33 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -9,10 +9,10 @@ git-format-patch - Prepare patches for e-mail submission
> SYNOPSIS
> --------
> [verse]
> -'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
> - [--attach[=<boundary>] | --inline[=<boundary>] |
> - [--no-attach]]
> - [-s | --signoff] [<common diff options>]
> +'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
> + [--thread[=<style>]]
> + [(--attach|--inline)[=<boundary>] | --no-attach]
> + [-s | --signoff]
> [-n | --numbered | -N | --no-numbered]
> [--start-number <n>] [--numbered-files]
> [--in-reply-to=Message-Id] [--suffix=.<sfx>]
> @@ -20,6 +20,7 @@ SYNOPSIS
> [--subject-prefix=Subject-Prefix]
> [--cc=<email>]
> [--cover-letter]
> + [<common diff options>]
> [ <since> | <revision range> ]
>
> DESCRIPTION
> @@ -170,18 +171,17 @@ if that is not set.
> --suffix=.<sfx>::
> Instead of using `.patch` as the suffix for generated
> filenames, use specified suffix. A common alternative is
> - `--suffix=.txt`.
> + `--suffix=.txt`. Leaving this empty will remove the `.patch`
> + suffix.
> +
Those asciidoc constructs in diff make me always wonder "Huh? A merge diff -cc?"... It's fine, of course.
Show 5 quoted lines
> -Note that you would need to include the leading dot `.` if you
> -want a filename like `0001-description-of-my-change.patch`, and
> -the first letter does not have to be a dot. Leaving it empty would
> -not add any suffix.
> +Note the leading character does not have to be a dot; for example, you
Maybe "Note that the" sounds and reads better.
Show 26 quoted lines
> +can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
>
> --no-binary::
> - Don't output contents of changes in binary files, just take note
> - that they differ. Note that this disable the patch to be properly
> - applied. By default the contents of changes in those files are
> - encoded in the patch.
> + Do not output contents of changes in binary files, instead
> + display a notice that those files changed. Patches generated
> + using this option cannot be applied properly, but they are
> + still useful for code review.
>
> --root::
> Treat the revision argument as a <revision range>, even if it
> @@ -192,10 +192,10 @@ not add any suffix.
>
> CONFIGURATION
> -------------
> -You can specify extra mail header lines to be added to each message
> -in the repository configuration, new defaults for the subject prefix
> -and file suffix, control attachments, and number patches when outputting
> -more than one.
> +You can specify extra mail header lines to be added to each message,
> +defaults for the subject prefix and file suffix, number patches when
> +outputting more than one patch, add "Cc:" headers, configure attachments,
> +and signoff patches with configuration variables.
Show 14 quoted lines
>
> ------------
> [format]
> @@ -243,8 +243,8 @@ $ git format-patch -M -B origin
> +
> Additionally, it detects and handles renames and complete rewrites
> intelligently to produce a renaming patch. A renaming patch reduces
> -the amount of text output, and generally makes it easier to review it.
> -Note that the "patch" program does not understand renaming patches, so
> +the amount of text output, and generally makes it easier to review.
> +Note that non-git "patch" programs won't understand renaming patches, so
> use it only when you know the recipient uses git to apply your patch.
>
> * Extract three topmost commits from the current branch and format them
Looks nice overall, especially the ones I'm not replying to ;)
Michael
Stephen Boyd
