git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH/RFC 4/5] test-tool: add a "historian" subcommand for building merge fixtures

From
Toon Claes <toon@iotcl.com>
Date
May 12, 2026, 10:54 UTC
Message-ID
<87lddooq2t.fsf@toon--20250203-5JQV3.mail-host-address-is-not-set>
In-Reply-To
<72c486312cde9a9fd2dedb60bc43c5c3e40a0d64.1778107405.git.gitgitgadget@gmail.com>
"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 93 quoted lines
> From: Johannes Schindelin <johannes.schindelin@gmx.de>
>
> The merge-replay tests added in a follow-up commit need a way to set
> up specific topologies with full control over blob contents, parent
> order, and per-side trees. Sequencing plumbing commands or driving
> plain `git fast-import` from shell quickly becomes unreadable for
> the kinds of scenarios that exercise non-trivial merge resolution
> (textual conflicts, semantic edits outside the conflict region,
> intentional limitations such as new content on one side).
>
> Add a small `test-tool historian` subcommand that reads a tight,
> shell-quoted, one-line-per-object DSL and feeds an equivalent stream
> to a `git fast-import` child process. Each blob and commit is given
> a logical name; the helper allocates fast-import marks on first use
> and emits a lightweight tag for every commit so tests can refer to
> the resulting object via `refs/tags/<name>`.
>
> The DSL has just two directives:
>
>   blob NAME LINE...
>   commit NAME BRANCH SUBJECT [from=NAME] [merge=NAME]... [PATH=BLOB]...
>
> A blob's content is the listed lines joined with `\n` (and a final
> `\n`); a commit's tree is exactly the listed PATH=BLOB pairs (the
> helper emits a `deleteall` so nothing leaks in from the implicit
> parent). Token splitting is delegated to `split_cmdline()` so quoted
> arguments work as in shell. Marks for parent references and file
> contents go through the same `strintmap`-backed name resolver, which
> keeps the helper itself trivially small: blob writing, tree
> construction, commit creation and merge-base computation are all
> handled by `git fast-import`.
>
> Note that the DSL reserves the names `from` and `merge` (with a
> trailing `=`) for parent specification; a tree path called `from` or
> `merge` cannot be expressed via this helper. That is acceptable here
> because every input is a tightly controlled test fixture and the
> filenames are chosen by the test author.
>
> The helper trusts its caller: malformed input results in a
> fast-import error rather than a friendly diagnostic.
>
> Wire the new subcommand into the Makefile and meson build, register
> it in `t/helper/test-tool.{c,h}`.
>
> Assisted-by: Claude Opus 4.7
> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
> ---
>  Makefile                  |   1 +
>  t/helper/meson.build      |   1 +
>  t/helper/test-historian.c | 189 ++++++++++++++++++++++++++++++++++++++
>  t/helper/test-tool.c      |   1 +
>  t/helper/test-tool.h      |   1 +
>  5 files changed, 193 insertions(+)
>  create mode 100644 t/helper/test-historian.c
>
> diff --git a/Makefile b/Makefile
> index cedc234173..b38678b484 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -832,6 +832,7 @@ TEST_BUILTINS_OBJS += test-hash-speed.o
>  TEST_BUILTINS_OBJS += test-hash.o
>  TEST_BUILTINS_OBJS += test-hashmap.o
>  TEST_BUILTINS_OBJS += test-hexdump.o
> +TEST_BUILTINS_OBJS += test-historian.o
>  TEST_BUILTINS_OBJS += test-json-writer.o
>  TEST_BUILTINS_OBJS += test-lazy-init-name-hash.o
>  TEST_BUILTINS_OBJS += test-match-trees.o
> diff --git a/t/helper/meson.build b/t/helper/meson.build
> index 675e64c010..704edd1e1f 100644
> --- a/t/helper/meson.build
> +++ b/t/helper/meson.build
> @@ -29,6 +29,7 @@ test_tool_sources = [
>    'test-hash.c',
>    'test-hashmap.c',
>    'test-hexdump.c',
> +  'test-historian.c',
>    'test-json-writer.c',
>    'test-lazy-init-name-hash.c',
>    'test-match-trees.c',
> diff --git a/t/helper/test-historian.c b/t/helper/test-historian.c
> new file mode 100644
> index 0000000000..2250d420c0
> --- /dev/null
> +++ b/t/helper/test-historian.c
> @@ -0,0 +1,189 @@
> +/*
> + * Build a small history out of a tiny declarative input. Used by tests
> + * that need specific merge topologies without long sequences of
> + * plumbing commands or fragile shell helpers.
> + *
> + * The historian reads stdin line by line and emits an equivalent
> + * stream to a `git fast-import` child process. It also allocates marks
> + * for named objects so tests can refer to commits and blobs by name.

Really appreciate you're introducing this command. I'm actually surprised no else did before.

Show 9 quoted lines
> + *
> + * Input directives (one per line, shell-style quoting):
> + *
> + *	blob NAME LINE1 LINE2 ...
> + *	    Each LINE becomes a content line in the blob; lines are
> + *	    joined with '\n' and the blob ends with a final '\n'. With
> + *	    no LINEs, the blob is empty.
> + *
> + *	commit NAME BRANCH SUBJECT [from=PARENT] [merge=PARENT]... [PATH=BLOB]...

I'm not sure how I feel about mixing named arguments (like `from=PARENT`) with the `PATH=BLOB` arguments? Obviously this tool isn't made for anything that's even close to production, but still feels strange. How about putting a double dash (`--`) before the paths, or using the `PATH:BLOB` syntax instead?

Show 5 quoted lines
> + *	    Creates a commit on refs/heads/BRANCH using the listed
> + *	    file=blob mappings as the entire tree (no inheritance from
> + *	    parents). Up to one `from=` and any number of `merge=`
> + *	    parents may be given. `from=` defaults to the current branch
> + *	    tip; if BRANCH has no tip yet, the commit becomes a root.

At GitLab in our Gitaly suite we have a similar tool as what you're introducing here, but there you have to specify the parent(s) for each commit and if you want to assign a ref to a commit, you have to be explicit about it. So I would replace `from=` and `merge=` with `parent=` and allow that to be occur zero or more times (this would also allow creating unrelated histories). And remove the mandatory argument BRANCH, and instead allow the command to accept a `branch=` argument.

If we'd take an example from the follow-up commit:
        # Setup:
        #       A (a) --- C (a, h) ----+--- M (a, g, h)
        #        \                    /
        #         +-- B (a, g) ------+
        #
        # Topic touches `g` only; main touches `h` only. The auto-merge
        # at M is clean.
        blob a "shared content"
        blob g guarded
        blob h host
        commit A main "A" a=a
        commit B topic "B (introduces g)" from=A a=a g=g
        commit C main "C (introduces h)" a=a h=h
        commit M main "Merge topic" merge=B a=a g=g h=h
I would suggest to rewrite that to:
        blob a "shared content"
        blob g guarded
        blob h host
        commit A "A" a:a
        commit B "B (introduces g)" parent=A branch=topic a:a g:g
        commit C "C (introduces h)" parent=A a:a h:h
        commit M "Merge topic" parent=A parent=B ref=main a:a g:g h:h

I realize this is less alike to git-fast-import(1), so I'd understand if you'd reject this idea.

-- 
Cheers,
Toon
Previous: Johannes Schindelin via GitGitGadgetNext: Johannes Schindelin
Message 14 of 19 in “replay: support replaying 2-parent merges”
  1. 0/5 replay: support replaying 2-parent mergesJohannes Schindelin via GitGitGadget, May 6, 2026
  2. 1/5 replay: support replaying 2-parent mergesJohannes Schindelin via GitGitGadget, May 6, 2026
  3. Phillip WoodMay 8, 2026
  4. Phillip WoodMay 8, 2026
  5. Johannes SchindelinMay 17, 2026
  6. Johannes SchindelinMay 17, 2026
  7. Kristoffer HaugsbakkMay 26, 2026
  8. Philippe BlainNov 5, 2026
  9. Philippe BlainNov 13, 2026
  10. 2/5 replay: short-circuit merge replay when parent and base trees are unchangedJohannes Schindelin via GitGitGadget, May 6, 2026
  11. 3/5 history.adoc: describe merge-replay support and its limitsJohannes Schindelin via GitGitGadget, May 6, 2026
  12. 5/5 t3454: cover merge-replay scenarios with the historian helperJohannes Schindelin via GitGitGadget, May 6, 2026
  13. 4/5 test-tool: add a "historian" subcommand for building merge fixturesJohannes Schindelin via GitGitGadget, May 6, 2026
  14. Toon ClaesMay 12, 2026
  15. Johannes SchindelinMay 17, 2026
  16. D. Ben KnobleMay 7, 2026
  17. Johannes SchindelinMay 7, 2026
  18. Ben KnobleMay 7, 2026
  19. Johannes SchindelinMay 17, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.