Skip to contentSkip to conversation

commit-tree: utilize parse-options api

PATCH Superseded Brandon Richardson 3 participants 5 messages Mar 1, 2019 – Mar 2, 2019 Documentation

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 commit-tree: utilize parse-options api

Rather than parse options manually, which is both difficult to read and error prone, parse options supplied to commit-tree using the parse-options api.

It was discovered that the --no-gpg-sign option was documented but not implemented in commit 70ddbd7767 (commit-tree: add missing --gpg-sign flag, 2019-01-19), and the existing implementation would attempt to translate the option as a tree oid. It was also suggested earlier in commit 55ca3f99ae (commit-tree: add and document --no-gpg-sign, 2013-12-13) that commit-tree should be migrated to utilize the parse-options api, which could help prevent mistakes like this in the future. Hence this change.

---

Notes:
GitHub Pull Request: https://github.com/brandon1024/git/pull/2
Travis CI Results: https://travis-ci.com/brandon1024/git/builds/102755598

 Documentation/git-commit-tree.txt |   8 +-
 builtin/commit-tree.c             | 159 ++++++++++++++++--------------
 parse-options.h                   |   9 ++
 3 files changed, 102 insertions(+), 74 deletions(-)
Documentation/git-commit-tree.txt +6 -2
index 002dae625e..f4e20b62a0 100644
@@ -23,6 +23,9 @@ Creates a new commit object based on the provided tree object and
 emits the new commit object id on stdout. The log message is read
 from the standard input, unless `-m` or `-F` options are given.
 
+When mixing `-m` and `-F` options, the commit log message will be
+composed in the order in which the options are given.
+
 A commit object may have any number of parents. With exactly one
 parent, it is an ordinary commit. Having more than one parent makes
 the commit a merge between several lines of history. Initial (root)
@@ -41,7 +44,7 @@ state was.
 OPTIONS
 -------
 <tree>::
-	An existing tree object
+	An existing tree object.
 
 -p <parent>::
 	Each `-p` indicates the id of a parent commit object.
@@ -52,7 +55,8 @@ OPTIONS
 
 -F <file>::
 	Read the commit log message from the given file. Use `-` to read
-	from the standard input.
+	from the standard input. This can be given more than once and the
+	content of each file becomes its own paragraph.
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
builtin/commit-tree.c +87 -72

193 lines not on this page · raw message

parse-options.h +9 -0
index 14fe32428e..a6ab338be3 100644
@@ -202,6 +202,15 @@ const char *optname(const struct option *opt, int flags);
 		BUG("option callback does not expect an argument"); \
 } while (0)
 
+/*
+ * Use this assertion for callbacks that expect to be called with NONEG,
+ * and require an argument be supplied.
+ */
+#define BUG_ON_OPT_NEG_NOARG(unset, arg) do { \
+	if((!unset) && (!arg)) \
+		BUG("option callback does not expect negation and requires an argument"); \
+} while(0)
+
 /*----- incremental advanced APIs -----*/
 
 enum {
Signature · 1 line
2.21.0
#1 lore raw

Review

Quoted 5 lines · Brandon Richardson
(quoted diff) +5 -0
+/*
+ * Use this assertion for callbacks that expect to be called with NONEG,
+ * and require an argument be supplied.
+ */
+#define BUG_ON_OPT_NEG_NOARG(unset, arg) do { \

I think this general concept is fine. It's a variant of BUG_ON_OPT_NEG(), so you'd use one or the other.

However, the implementation:

Review

Quoted 2 lines
(quoted diff) +2 -0
+	if((!unset) && (!arg)) \
+		BUG("option callback does not expect negation and requires an argument"); \

does not really make sense. If "!unset" is true, then we know that "!arg" will always be true as well. So this collapse down to "!unset", which is the same as BUG_ON_OPT_NEG().

I think you want an "OR". Or even separate conditions, since really this is just implying OPT_NEG(). In fact, you could implement and explain it like this:

parse-options.h +12 -0
index 14fe32428e..d46f89305c 100644
@@ -202,6 +202,18 @@ const char *optname(const struct option *opt, int flags);
 		BUG("option callback does not expect an argument"); \
 } while (0)
 
+/*
+ * Similar to the assertions above, but checks that "arg" is always non-NULL.
+ * I.e., that we expect the NOARG and OPTARG flags _not_ to be set. Since
+ * negation is the other common cause of a NULL arg, this also implies
+ * BUG_ON_OPT_NEG(), letting you declare both assertions in a single line.
+ */
+#define BUG_ON_OPT_NOARG(unset, arg) do { \
+	BUG_ON_OPT_NEG(unset); \
+	if (!(arg)) \
+		BUG("option callback require an argument"); \
+} while (0)
+
 /*----- incremental advanced APIs -----*/
 
 enum {

-Peff

#2 lore raw
Quoted 3 lines · Jeff King

Review

Quoted 2 lines · Brandon Richardson
(quoted diff) +2 -0
+     if((!unset) && (!arg)) \
+             BUG("option callback does not expect negation and requires an argument"); \

Peff didn't highlight this, but compare your use of macro arguments against his...

parse-options.h const char *optname(const struct option *opt, int flags); · line 215

Quoted 11 lines
parse-options.h +11 -0
+/*
+ * Similar to the assertions above, but checks that "arg" is always non-NULL.
+ * I.e., that we expect the NOARG and OPTARG flags _not_ to be set. Since
+ * negation is the other common cause of a NULL arg, this also implies
+ * BUG_ON_OPT_NEG(), letting you declare both assertions in a single line.
+ */
+#define BUG_ON_OPT_NOARG(unset, arg) do { \
+       BUG_ON_OPT_NEG(unset); \
+       if (!(arg)) \
+               BUG("option callback require an argument"); \
+} while (0)

Note, in particular how Peff used !(arg) rather than (!arg) in your patch. This distinction is subtle but important enough to warrant being called out. The reason that Peff did it this way (the _correct_ way) is that, as a macro argument, 'arg' may be a complex expression rather than a simple boolean. for instance, a caller could conceivably invoke the macro as:

    BUG_ON_OPT_NOARG(unset, foo || bar)

Let's say that 'foo' and 'bar' are both true. With Peff's version, when the macro is expanded, that expression becomes:

    !(true || true)

which evaluates to false as expected and intended. With your version, it expands to:

    (!true || true)

which evaluates to true (since ! has higher precedence than ||), which is a very different and very unexpected (and likely wrong) result.

#3 lore raw

Hi Eric,

Quoted 8 lines · Eric Sunshine

Note, in particular how Peff used !(arg) rather than (!arg) in your patch. This distinction is subtle but important enough to warrant being called out. The reason that Peff did it this way (the _correct_ way) is that, as a macro argument, 'arg' may be a complex expression rather than a simple boolean. for instance, a caller could conceivably invoke the macro as:

    BUG_ON_OPT_NOARG(unset, foo || bar)

Thanks for pointing this out. I caught this shortly after I submitted v2. I hadn't
considered that the argument could be an expression. Will fix in v3.

#4 lore raw
In reply to Jeff King
Quoted 15 lines · Jeff King

I think you want an "OR". Or even separate conditions, since really this is just implying OPT_NEG(). In fact, you could implement and explain it like this:

parse-options.h +3 -0
index 14fe32428e..d46f89305c 100644
@@ -202,6 +202,18 @@ const char *optname(const struct option *opt, int flags);
                BUG("option callback does not expect an argument"); \
 } while (0)
 
+/*
+ * Similar to the assertions above, but checks that "arg" is always non-NULL.
+ * I.e., that we expect the NOARG and OPTARG flags _not_ to be set. Since

parse-options.h const char *optname(const struct option *opt, int flags); · line 217

Quoted 10 lines
parse-options.h +9 -0
+ * negation is the other common cause of a NULL arg, this also implies
+ * BUG_ON_OPT_NEG(), letting you declare both assertions in a single line.
+ */
+#define BUG_ON_OPT_NOARG(unset, arg) do { \
+       BUG_ON_OPT_NEG(unset); \
+       if (!(arg)) \
+               BUG("option callback require an argument"); \
+} while (0)
+
 /*----- incremental advanced APIs -----*/

Ahh yes. I had originally used ((!unset) || (!arg)), and second guessed myself before I submitted v2. However, I much prefer your solution which reuses BUG_ON_OPT_NEG(). I'll switch to that :-)

Brandon