Re: [PATCH v2 4/8] builtin/reflog: implement subcommand to write new entries

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Jul 28, 2025, 15:33 UTC
Message-ID: <6414dbfd-6f34-48d1-aa3f-3fe7998f80af@app.fastmail.com>
In-Reply-To: <20250725-pks-reflog-append-v2-4-e4e7cbe3f578@pks.im>

On Fri, Jul 25, 2025, at 08:58, Patrick Steinhardt wrote:

Show 5 quoted lines

> While we provide a couple of subcommands in git-reflog(1) to remove
> reflog entries, we don't provide any to write new entries. Obviously
> this is not an operation that really would be needed for many use cases
> out there, or otherwise people would have complained that such a command
> does not exist yet.

This command will allow you to write a simpler unique marker (without having to make a marker-ref for a ref) that can be used to find back to a specific point.

I’ve had some use for that. I used git-update-ref(1) for that because of `-m` (as well as plumbing-for-scripting).

Show 24 quoted lines

> diff --git a/Documentation/git-reflog.adoc
> b/Documentation/git-reflog.adoc
> index c3801b82fb6..c8389810273 100644
> --- a/Documentation/git-reflog.adoc
> +++ b/Documentation/git-reflog.adoc
> @@ -12,6 +12,7 @@ SYNOPSIS
>  git reflog [show] [<log-options>] [<ref>]
>  git reflog list
>  git reflog exists <ref>
> +git reflog write <ref> <old-oid> <new-oid> <message>
>  git reflog delete [--rewrite] [--updateref]
>  	[--dry-run | -n] [--verbose] <ref>@{<specifier>}...
>  git reflog drop [--all [--single-worktree] | <refs>...]
> @@ -47,6 +48,12 @@ The "exists" subcommand checks whether a ref has a
> reflog.  It exits
>  with zero status if the reflog exists, and non-zero status if it does
>  not.
>
> +The "write" subcommand writes a single entry to the reflog of a given
> +reference. This new entry is appended to the reflog and will thus become
> +the most recent entry. Both the old and new object IDs must not be
> +abbreviated and must point to existing objects. The reflog message gets
> +normalized.
> +

You have to give the full refname to this subcommand. `git reflog write ... branch <msg>` will update the reflog for the one-level ref `branch`. But I’m used to using git-reflog(1) with a name like `branch` and it using `refs/heads/branch` if it exists. At least that’s how the default `git reflog show` behaves.

Which means that

    git reflog write ... refs/heads/branch <msg>
    git reflog branch

Will show that written reflog.

Whereas this

    git reflog write ... branch <msg>
    git reflog branch

Will show one entry since `branch` is the one-level ref `branch`, not `refs/heads/branch`. Now it looks like `write` truncated the reflog and wrote a new reflog message (if you mistakenly think that `branch` is a branch).

It isn’t clear to me how the current doc guides me in the correct direction here.

I tried `git reflog drop`[1] and it can deal with a branch like `branch`. It doesn’t need to be told `refs/heads/branch`.

>  The "delete" subcommand deletes single entries from the reflog, but
>  not the reflog itself. Its argument must be an _exact_ entry (e.g. "`git
>  reflog delete master@{2}`"). This subcommand is also typically not used