From: Eric Sunshine <sunsh...@sunshineco.com> > > On Sun, Jan 26, 2014 at 12:00 PM, Christian Couder > <chrisc...@tuxfamily.org> wrote: >> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org> >> --- >> diff --git a/Documentation/git-interpret-trailers.txt >> b/Documentation/git-interpret-trailers.txt >> new file mode 100644 >> index 0000000..f74843e >> --- /dev/null >> +++ b/Documentation/git-interpret-trailers.txt >> @@ -0,0 +1,137 @@ >> +git-interpret-trailers(1) >> +========================= >> + >> +NAME >> +---- >> +git-interpret-trailers - help add stuctured information into commit messages >> + >> +SYNOPSIS >> +-------- >> +[verse] >> +'git interpret-trailers' [--trim-empty] [--infile=file] [<token[=value]>...] > > Would it be more consistent with existing documentation to format this as so? > > [--infile=<file>] [<token>[=<value>]]...
No, it would be very inconsistent: $ grep '\.\.\.\]' *.txt | wc -l 103 $ grep '\]\.\.\.' *.txt | wc -l 0 >> +DESCRIPTION >> +----------- >> +Help add RFC 822 like headers, called 'trailers', at the end of the > > s/822 like/822-like/ Ok. > Was the suggestion, early in the discussion, to use "footer" rather > than "trailer" dismissed? During the early discussions people initially talked about "footer" while Junio and others talked about "trailer". See: http://thread.gmane.org/gmane.comp.version-control.git/236429/ http://thread.gmane.org/gmane.comp.version-control.git/236770/ I have no preference for one or the other, but by default I use what Junio uses. >> +otherwise free-form part of a commit message. >> + >> +Unless `--infile=file` is used, this command is a filter. It reads the >> +standard input for a commit message and apply the `token` arguments, > > s/apply/applies/ Ok. >> +if any, to this message. The resulting message is emited on the >> +standard output. >> + >> +Some configuration variables control the way the `token` arguments are >> +applied to the message and the way any existing trailer in the message >> +is changed. They also make it possible to automatically add some >> +trailers. >> + >> +By default, a 'token=value' or 'token:value' argument will be added >> +only if no trailer with the same (token, value) pair is already in the >> +message. The 'token' and 'value' parts will be trimmed to remove >> +starting and trailing white spaces, and the resulting trimmed 'token' > > Other git documentation uniformly spells it as "whitespace" rather > than "white spaces". You are right I will change that. >> +and 'value' will appear in the message like this: >> + >> +------------------------------------------------ >> +token: value >> +------------------------------------------------ >> + >> +By default, if there are already trailers with the same 'token' the >> +trailer will appear just after the last trailer with the same > > It might be a bit clearer to say "the _new_ trailer will appear...". Ok. >> +'token'. Otherwise it will appear at the end of the message. >> + >> +Note that 'trailers' do not follow and are not intended to follow many >> +rules that are in RFC 822. For example they do not follow the line >> +breaking rules, the encoding rules and probably many other rules. >> + >> +Trailers have become a de facto standard way to add helpful structured >> +information into commit messages. For example the well known >> +"Signed-off-by: " trailer is used by many projects like the Linux >> +kernel and Git. > > This "justification" paragraph might make more sense near or at the > very the top of the Description section. Yeah, or maybe I can remove it entirely. >> +OPTIONS >> +------- >> +--trim-empty:: >> + If the 'value' part of any trailer contains onlywhite spaces, > > s/onlywhite spaces/only whitespace/ Ok. >> + the whole trailer will be removed from the resulting message. >> + >> +----infile=file:: >> + Read the commit message from `file` instead of the standard >> + input. >> + >> +CONFIGURATION VARIABLES >> +----------------------- >> + >> +trailer.<token>.key:: >> + This 'key' will be used instead of 'token' in the >> + trailer. After some alphanumeric characters, it can contain >> + some non alphanumeric characters like ':', '=' or '#' that will >> + be used instead of ':' to separate the token from the value in >> + the trailer, though the default ':' is more standard. >> + >> +trailer.<token>.where:: >> + This can be either `after`, which is the default, or >> + `before`. If it is `before`, then a trailer with the specified >> + token, will appear before, instead of after, other trailers >> + with the same token, or otherwise at the beginning, instead of >> + at the end, of all the trailers. >> + >> +trailer.<token>.ifexist:: >> + This option makes it possible to chose what action will be > > s/chose/choose/ Ok. >> + performed when there is already at least one trailer with the >> + same token in the message. >> ++ >> +The valid values for this option are: `addIfDifferent` (this is the >> +default), `addIfDifferentNeighbor`, `add`, `overwrite` or `doNothing`. >> ++ >> +With `addIfDifferent`, a new trailer will be added only if no trailer >> +with the same (token, value) pair is already in the message. >> ++ >> +With `addIfDifferentNeighbor`, a new trailer will be added only if no >> +trailer with the same (token, value) pair is above or below the line >> +where the new trailer will be added. >> ++ >> +With `add`, a new trailer will be added, even if some trailers with >> +the same (token, value) pair are already in the message. >> ++ >> +With `overwrite`, the new trailer will overwrite an existing trailer >> +with the same token. >> ++ >> +With `doNothing`, nothing will be done, that is no new trailer will be >> +added if there is already one with the same token in the message. >> + >> +trailer.<token>.ifmissing:: >> + This option makes it possible to chose what action will be > > s/chose/choose/ Ok. >> + performed when there is not yet any trailer with the same >> + token in the message. >> ++ >> +The valid values for this option are: `add` (this is the default) and >> +`doNothing`. >> ++ >> +With `add`, a new trailer will be added. >> ++ >> +With `doNothing`, nothing will be done. >> + >> +trailer.<token>.command:: >> + This option can be used to specify a shell command that will >> + be used to automatically add or modify a trailer with the >> + specified 'token'. >> ++ >> +When this option is specified, it is like if a special 'token=value' >> +argument is added at the end of the command line, where 'value' will >> +be given by the standard output of the specified command. > > What happens if the text returned by the command has multiple lines? The 'value' part of trailer will be on multiple lines. > Should the documentation say something about this? I think it is better left as unspecified because we might want to print a warning, or perhaps error out in this case. Thanks, Christian. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
