[PATCH 1/8] ahead-behind: create empty builtin

["Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com>]

From: Derrick Stolee <derrickstolee@github.com>

The 'git ahead-behind' builtin _will_ allow users to specify multiple
tip revisions relative to a common base and _will_ report the number of
commits on each side of the symmetric difference between each tip and
the base. However, that algorithm is not implemented yet and instead
this change introduces the builtin and the basic boilerplate for a new
builtin.

This builtin could be replaced with multiple invocations of 'git
rev-list --count <base>..<tip>' (for ahead values) and 'git rev-list
--count <tip>..<base>' (for behind values). However, it is important to
be able to batch these calls into a single process.

For example, we will be able to track all local branches relative to an
upstream branch using an invocation such as

  git for-each-ref --format=%(refname) refs/heads/* |
    git ahead-behind --base=origin/main --stdin

This would report each local branch and how far ahead or behind it is
relative to the remote branch 'origin/main'. This could be used to
signal some branches are very old and need to be updated via 'git
rebase' or deleted. We will see in future changes how such commit
counting can be done efficiently within a single process (and a single
commit walk) instead of multiple processes.

For now, only 'git ahead-behind -h' works, and the builtin reports
failure and shows the usage if the '--base' option is skipped. The
documentation is light. These will be updated in the coming changes.

Signed-off-by: Derrick Stolee <derrickstolee@github.com>
---
 .gitignore                         |  1 +
 Documentation/git-ahead-behind.txt | 62 ++++++++++++++++++++++++++++++
 Makefile                           |  1 +
 builtin.h                          |  1 +
 builtin/ahead-behind.c             | 30 +++++++++++++++
 git.c                              |  1 +
 t/t4218-ahead-behind.sh            | 17 ++++++++
 7 files changed, 113 insertions(+)
 create mode 100644 Documentation/git-ahead-behind.txt
 create mode 100644 builtin/ahead-behind.c
 create mode 100755 t/t4218-ahead-behind.sh

diff --git a/.gitignore b/.gitignore
index e875c590545..cc064a4817a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,7 @@
 /bin-wrappers/
 /git
 /git-add
+/git-ahead-behind
 /git-am
 /git-annotate
 /git-apply
diff --git a/Documentation/git-ahead-behind.txt b/Documentation/git-ahead-behind.txt
new file mode 100644
index 00000000000..0e2f989a1a0
--- /dev/null
+++ b/Documentation/git-ahead-behind.txt
@@ -0,0 +1,62 @@
+git-ahead-behind(1)
+===================
+
+NAME
+----
+git-ahead-behind - Count the commits on each side of a revision range
+
+SYNOPSIS
+--------
+[verse]
+'git ahead-behind' --base=<ref> [ --stdin | <revs> ]
+
+DESCRIPTION
+-----------
+
+Given a list of commit ranges, report the number of commits reachable from
+each of the sides of the range, but not the other. Consider a commit range
+specified as `<base>...<tip>`, allowing for the following definitions:
+
+* The `<tip>` is *ahead* of `<base>` by the number of commits reachable
+  from `<tip>` but not reachable from `<base>`. This is the same as the
+  number of the commits in the range `<base>..<tip>`.
+
+* The `<tip>` is *behind* `<base>` by the number of commits reachable from
+  `<base>` but not reachble from `<tip>`. This is the same as the number
+  of commits in the range `<tip>..<base>`.
+
+The sum of the ahead and behind counts equals the number of commits in the
+symmetric difference, the range `<base>...<tip>`.
+
+Multiple revisions may be specified, and they are all compared against a
+common base revision, as specified by the `--base` option. The values are
+reported to stdout one line at a time as follows:
+
+---
+  <rev> <ahead> <behind>
+---
+
+There will be exactly one line per input revision, but the lines may be
+in an arbitrary order.
+
+
+OPTIONS
+-------
+--base=<ref>::
+	Specify that `<ref>` should be used as a common base for all
+	provided revisions that are not specified in the form of a range.
+
+--stdin::
+	Read revision tips and ranges from stdin instead of from the
+	command-line.
+
+
+SEE ALSO
+--------
+linkgit:git-branch[1]
+linkgit:git-rev-list[1]
+linkgit:git-tag[1]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Makefile b/Makefile
index 50ee51fde32..691f84e8d4e 100644
--- a/Makefile
+++ b/Makefile
@@ -1199,6 +1199,7 @@ LIB_OBJS += xdiff-interface.o
 LIB_OBJS += zlib.o
 
 BUILTIN_OBJS += builtin/add.o
+BUILTIN_OBJS += builtin/ahead-behind.o
 BUILTIN_OBJS += builtin/am.o
 BUILTIN_OBJS += builtin/annotate.o
 BUILTIN_OBJS += builtin/apply.o
diff --git a/builtin.h b/builtin.h
index 46cc7897898..1ae168fa3e3 100644
--- a/builtin.h
+++ b/builtin.h
@@ -108,6 +108,7 @@ void setup_auto_pager(const char *cmd, int def);
 int is_builtin(const char *s);
 
 int cmd_add(int argc, const char **argv, const char *prefix);
+int cmd_ahead_behind(int argc, const char **argv, const char *prefix);
 int cmd_am(int argc, const char **argv, const char *prefix);
 int cmd_annotate(int argc, const char **argv, const char *prefix);
 int cmd_apply(int argc, const char **argv, const char *prefix);
diff --git a/builtin/ahead-behind.c b/builtin/ahead-behind.c
new file mode 100644
index 00000000000..a56cc565def
--- /dev/null
+++ b/builtin/ahead-behind.c
@@ -0,0 +1,30 @@
+#include "builtin.h"
+#include "parse-options.h"
+#include "config.h"
+
+static const char * const ahead_behind_usage[] = {
+	N_("git ahead-behind --base=<ref> [ --stdin | <revs> ]"),
+	NULL
+};
+
+int cmd_ahead_behind(int argc, const char **argv, const char *prefix)
+{
+	const char *base_ref = NULL;
+	int from_stdin = 0;
+
+	struct option ahead_behind_opts[] = {
+		OPT_STRING('b', "base", &base_ref, N_("base"), N_("base reference to process")),
+		OPT_BOOL(0 , "stdin", &from_stdin, N_("read rev names from stdin")),
+		OPT_END()
+	};
+
+	argc = parse_options(argc, argv, NULL, ahead_behind_opts,
+			     ahead_behind_usage, PARSE_OPT_KEEP_UNKNOWN_OPT);
+
+	if (!base_ref)
+		usage_with_options(ahead_behind_usage, ahead_behind_opts);
+
+	git_config(git_default_config, NULL);
+
+	return 0;
+}
diff --git a/git.c b/git.c
index 6171fd6769d..64e3d493561 100644
--- a/git.c
+++ b/git.c
@@ -467,6 +467,7 @@ static int run_builtin(struct cmd_struct *p, int argc, const char **argv)
 
 static struct cmd_struct commands[] = {
 	{ "add", cmd_add, RUN_SETUP | NEED_WORK_TREE },
+	{ "ahead-behind", cmd_ahead_behind, RUN_SETUP },
 	{ "am", cmd_am, RUN_SETUP | NEED_WORK_TREE },
 	{ "annotate", cmd_annotate, RUN_SETUP },
 	{ "apply", cmd_apply, RUN_SETUP_GENTLY },
diff --git a/t/t4218-ahead-behind.sh b/t/t4218-ahead-behind.sh
new file mode 100755
index 00000000000..bc08f1207a0
--- /dev/null
+++ b/t/t4218-ahead-behind.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+
+test_description='git ahead-behind command-line options'
+
+. ./test-lib.sh
+
+test_expect_success 'git ahead-behind -h' '
+	test_must_fail git ahead-behind -h >out &&
+	grep "usage:" out
+'
+
+test_expect_success 'git ahead-behind without --base' '
+	test_must_fail git ahead-behind HEAD 2>err &&
+	grep "usage:" err
+'
+
+test_done
-- 
gitgitgadget