[RFC] config-batch: a new builtin for tools querying config

.gitignore

@@ -44,6 +44,7 @@
 /git-commit-graph
 /git-commit-tree
 /git-config
+/git-config-batch
 /git-count-objects
 /git-credential
 /git-credential-cache

Documentation/git-config-batch.adoc

@@ -0,0 +1,45 @@
+git-config-batch(1)
+===================
+
+NAME
+----
+git-config-batch - Get and set options using machine-parseable interface
+
+
+SYNOPSIS
+--------
+[verse]
+'git config-batch' <options>
+
+DESCRIPTION
+-----------
+Tools frequently need to change their behavior based on values stored in
+Git's configuration files. These files may have complicated conditions
+for including extra files, so it is difficult to produce an independent
+parser. To avoid executing multiple processes to discover or modify
+multiple configuration values, the `git config-batch` command allows a
+single process to handle multiple requests using a machine-parseable
+interface across `stdin` and `stdout`.
+
+PROTOCOL
+--------
+By default, the protocol uses line feeds (`LF`) to signal the end of a
+command over `stdin` or a response over `stdout`.
+
+The protocol will be extended in the future, and consumers should be
+resilient to older Git versions not understanding the latest command
+set. Thus, if the Git version includes the `git config-batch` builtin
+but doesn't understand an input command, it will return a single line
+response:
+
+```
+unknown_command LF
+```
+
+SEE ALSO
+--------
+linkgit:git-config[1]
+
+GIT
+---
+Part of the linkgit:git[1] suite

Documentation/meson.build

@@ -29,6 +29,7 @@ manpages = {
   'git-commit-tree.adoc' : 1,
   'git-commit.adoc' : 1,
   'git-config.adoc' : 1,
+  'git-config-batch.adoc' : 1,
   'git-count-objects.adoc' : 1,
   'git-credential-cache--daemon.adoc' : 1,
   'git-credential-cache.adoc' : 1,

Makefile

@@ -1390,6 +1390,7 @@ BUILTIN_OBJS += builtin/commit-graph.o
 BUILTIN_OBJS += builtin/commit-tree.o
 BUILTIN_OBJS += builtin/commit.o
 BUILTIN_OBJS += builtin/config.o
+BUILTIN_OBJS += builtin/config-batch.o
 BUILTIN_OBJS += builtin/count-objects.o
 BUILTIN_OBJS += builtin/credential-cache--daemon.o
 BUILTIN_OBJS += builtin/credential-cache.o

builtin.h

@@ -68,12 +68,18 @@
  *
  * . Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`.
  *
+ * . Add 'builtin/foo.c' to the 'builtin_sources' array in 'meson.build'.
+ *
  * Additionally, if `foo` is a new command, there are 4 more things to do:
  *
  * . Add tests to `t/` directory.
  *
+ * . Add the test script to 'integration_tests' in  't/meson.build'.
+ *
  * . Write documentation in `Documentation/git-foo.adoc`.
  *
+ * . Add 'git-foo.adoc' to the manpages list in 'Documentation/meson.build'.
+ *
  * . Add an entry for `git-foo` to `command-list.txt`.
  *
  * . Add an entry for `/git-foo` to `.gitignore`.
@@ -167,6 +173,7 @@ int cmd_commit(int argc, const char **argv, const char *prefix, struct repositor
 int cmd_commit_graph(int argc, const char **argv, const char *prefix, struct repository *repo);
 int cmd_commit_tree(int argc, const char **argv, const char *prefix, struct repository *repo);
 int cmd_config(int argc, const char **argv, const char *prefix, struct repository *repo);
+int cmd_config_batch(int argc, const char **argv, const char *prefix, struct repository *repo);
 int cmd_count_objects(int argc, const char **argv, const char *prefix, struct repository *repo);
 int cmd_credential(int argc, const char **argv, const char *prefix, struct repository *repo);
 int cmd_credential_cache(int argc, const char **argv, const char *prefix, struct repository *repo);

builtin/config-batch.c

@@ -0,0 +1,161 @@
+#define USE_THE_REPOSITORY_VARIABLE
+#include "builtin.h"
+#include "config.h"
+#include "environment.h"
+#include "parse-options.h"
+#include "strbuf.h"
+#include "string-list.h"
+
+static const char *const builtin_config_batch_usage[] = {
+	N_("git config-batch <options>"),
+	NULL
+};
+
+#define UNKNOWN_COMMAND "unknown_command"
+
+static int emit_response(const char *response, ...)
+{
+	va_list params;
+	const char *token;
+
+	printf("%s", response);
+
+	va_start(params, response);
+	while ((token = va_arg(params, const char *)))
+		printf(" %s", token);
+	va_end(params);
+
+	printf("\n");
+	fflush(stdout);
+	return 0;
+}
+
+/**
+ * A function pointer type for defining a command. The function is
+ * responsible for handling different versions of the command name.
+ *
+ * Provides the remaining 'data' for the command, to be parsed by
+ * the function as needed according to its parsing rules.
+ *
+ * These functions should only return a negative value if they result
+ * in such a catastrophic failure that the process should end.
+ *
+ * Return 0 on success.
+ */
+typedef int (*command_fn)(struct repository *repo,
+			  char *data, size_t data_len);
+
+static int unknown_command(struct repository *repo UNUSED,
+			  char *data UNUSED, size_t data_len UNUSED)
+{
+	return emit_response(UNKNOWN_COMMAND, NULL);
+}
+
+struct command {
+	const char *name;
+	command_fn fn;
+	int version;
+};
+
+static struct command commands[] = {
+	/* unknown_command must be last. */
+	{
+		.name = "",
+		.fn   = unknown_command,
+	},
+};
+
+#define COMMAND_COUNT ((size_t)(sizeof(commands) / sizeof(*commands)))
+
+/**
+ * Process a single line from stdin and process the command.
+ *
+ * Returns 0 on successful processing of command, including the
+ * unknown_command output.
+ *
+ * Returns 1 on natural exit due to exist signal of empty line.
+ *
+ * Returns negative value on other catastrophic error.
+ */
+static int process_command(struct repository *repo)
+{
+	static struct strbuf line = STRBUF_INIT;
+	struct string_list tokens = STRING_LIST_INIT_NODUP;
+	const char *command;
+	int version;
+	char *data = NULL;
+	size_t data_len = 0;
+	int res = 0;
+
+	strbuf_getline(&line, stdin);
+
+	if (!line.len)
+		return 1;
+
+	/* Parse out the first two tokens, command and version. */
+	string_list_split_in_place(&tokens, line.buf, " ", 2);
+
+	if (tokens.nr < 2) {
+		res = error(_("expected at least 2 tokens, got %"PRIu32),
+			    (uint32_t)tokens.nr);
+		goto cleanup;
+	}
+
+	command = tokens.items[0].string;
+
+	if (!git_parse_int(tokens.items[1].string, &version)) {
+		res = error(_("unable to parse '%s' to integer"),
+			    tokens.items[1].string);
+		goto cleanup;
+	}
+
+	if (tokens.nr >= 3) {
+		data = tokens.items[2].string;
+		data_len = strlen(tokens.items[2].string);
+	}
+
+	for (size_t i = 0; i < COMMAND_COUNT; i++) {
+		/*
+		 * Run the ith command if we have hit the unknown
+		 * command or if the name and version match.
+		 */
+		if (!commands[i].name[0] ||
+		    (!strcmp(command, commands[i].name) &&
+		     commands[i].version == version)) {
+			res = commands[i].fn(repo, data, data_len);
+			goto cleanup;
+		}
+	}
+
+	BUG(_("scanned to end of command list, including 'unknown_command'"));
+
+cleanup:
+	strbuf_reset(&line);
+	string_list_clear(&tokens, 0);
+	return res;
+}
+
+int cmd_config_batch(int argc,
+		     const char **argv,
+		     const char *prefix,
+		     struct repository *repo)
+{
+	int res = 0;
+	struct option options[] = {
+		OPT_END(),
+	};
+
+	show_usage_with_options_if_asked(argc, argv,
+					 builtin_config_batch_usage, options);
+
+	argc = parse_options(argc, argv, prefix, options, builtin_config_batch_usage,
+			     0);
+
+	repo_config(repo, git_default_config, NULL);
+
+	while (!(res = process_command(repo)));
+
+	if (res == 1)
+		return 0;
+	die(_("an unrecoverable error occurred during command execution"));
+}

command-list.txt

@@ -83,6 +83,7 @@ git-commit                              mainporcelain           history
 git-commit-graph                        plumbingmanipulators
 git-commit-tree                         plumbingmanipulators
 git-config                              ancillarymanipulators           complete
+git-config-batch                        plumbinginterrogators
 git-count-objects                       ancillaryinterrogators
 git-credential                          purehelpers
 git-credential-cache                    purehelpers

git.c

@@ -557,6 +557,7 @@ static struct cmd_struct commands[] = {
 	{ "commit-graph", cmd_commit_graph, RUN_SETUP },
 	{ "commit-tree", cmd_commit_tree, RUN_SETUP },
 	{ "config", cmd_config, RUN_SETUP_GENTLY | DELAY_PAGER_CONFIG },
+	{ "config-batch", cmd_config_batch, RUN_SETUP_GENTLY },
 	{ "count-objects", cmd_count_objects, RUN_SETUP },
 	{ "credential", cmd_credential, RUN_SETUP_GENTLY | NO_PARSEOPT },
 	{ "credential-cache", cmd_credential_cache },

meson.build

@@ -582,6 +582,7 @@ builtin_sources = [
   'builtin/commit-tree.c',
   'builtin/commit.c',
   'builtin/config.c',
+  'builtin/config-batch.c',
   'builtin/count-objects.c',
   'builtin/credential-cache--daemon.c',
   'builtin/credential-cache.c',

t/meson.build

@@ -186,6 +186,7 @@ integration_tests = [
   't1309-early-config.sh',
   't1310-config-default.sh',
   't1311-config-optional.sh',
+  't1312-config-batch.sh',
   't1350-config-hooks-path.sh',
   't1400-update-ref.sh',
   't1401-symbolic-ref.sh',

t/t1312-config-batch.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+
+test_description='Test git config-batch'
+
+. ./test-lib.sh
+
+test_expect_success 'no commands' '
+	echo | git config-batch >out &&
+	test_must_be_empty out
+'
+
+test_expect_success 'unknown_command' '
+	echo unknown_command >expect &&
+	echo "bogus 1 line of tokens" >in &&
+	git config-batch >out <in &&
+	test_cmp expect out
+'
+
+test_expect_success 'failed to parse version' '
+	echo "bogus BAD_VERSION line of tokens" >in &&
+	test_must_fail git config-batch 2>err <in &&
+	test_grep BAD_VERSION err
+'
+
+test_done