Re: [PATCH v9 11/11] Documentation: add documentation for 'git interpret-trailers'

Hi,

On Wed, Apr 2, 2014 at 2:39 AM, Jonathan Nieder [off-list ref] wrote:

(culling cc list)
Hi,

Christian Couder wrote:

quoted

[Subject: Documentation: add documentation for 'git interpret-trailers']

Signed-off-by: Christian Couder <redacted>

This should be squashed into the patch that introduces the
interpret-trailers command, IMHO (or if it should be reviewed
separately, it can be an earlier patch).  That way, someone looking at
when the command was introduced and wanting to understand what it was
originally meant to do has the information close by.

Well, the series is not very long, so this patch is quite close to the
beginning anyway.

Thanks for picking up the 'git commit --fixes' topic and your steady
work improving the series.

[...]

quoted

--- /dev/null
+++ b/Documentation/git-interpret-trailers.txt

@@ -0,0 +1,123 @@
+git-interpret-trailers(1)
+=========================
+
+NAME
+----
+git-interpret-trailers - help add stuctured information into commit messages
+
+SYNOPSIS
+--------
+[verse]
+'git interpret-trailers' [--trim-empty] [(<token>[(=|:)<value>])...]
+
+DESCRIPTION
+-----------
+Help add RFC 822-like headers, called 'trailers', at the end of the
+otherwise free-form part of a commit message.
+
+This command is a filter. It reads the standard input for a commit
+message and applies the `token` arguments, if any, to this
+message. The resulting message is emited on the standard output.

Do you have an example?  Does it work like this?

        $ git interpret-trailers 'signoff=Jonathan Nieder [off-list ref]' <<EOF
        > foo bar baz qux
        > EOF
        foo bar baz qux

        Signed-off-by: Jonathan Nieder [off-list ref]
        $

Yeah, that's the idea. But you need to run something like:

$ git config trailer.signoff.key "Signed-off-by:"

to configure it properly first.

By the way trying your example, I found that it is not currently
adding an empty line before the s-o-b.
I will have a look.

A short EXAMPLES section could help.

Yeah, it is planned, but not yet implemented, as written in patch 0/11:

"The following features are planned but not yet implemented:
        - add more tests related to commands
        - add examples in documentation
        - integration with "git commit""

If I am understanding it correctly, would a name like 'git add-trailers'
work?

It could work but it can modify, not just add trailers.

How do I read back the trailers later?

Why do you want to read them back?
Right now it should be used in hooks to modify commit messages.

[...]

quoted

+By default, a 'token=value' or 'token:value' argument will be added
+only if

Why support both '=' and ':'?  Using just one would make it easier to
grep through scripts to see who is adding signoffs.

That was already discussed previously.
The reason is that people are used to "token=value" for command line
arguments, but trailers appears in the result as "token: value", so it
is better for the user if we support both.

Thanks,
Christian.