Support building a specific Git ref from a local repository context

Description

docker buildx build already supports pinning a remote Git context to a branch, tag, commit, or checksum. That makes remote Git builds reproducible without depending on whatever happens to be checked out somewhere else.

I would like the same kind of workflow for local Git repositories.

Today, if I am in a local repository and run:

docker buildx build .

Buildx builds the current working tree. If I want to build an older commit, tag, or branch from the same local repo, I have to change the checkout first:

git checkout <commit-or-tag>
docker buildx build .

That works, but it is awkward in practice. It mutates the working tree, can get in the way of uncommitted work, and makes it harder to script builds across multiple refs. It also means local repositories do not have the same ref-pinning workflow that remote Git contexts already have.

Expected behavior

There should be a way to build a specific Git ref from a local repository without changing the current checkout.

For example, the exact syntax could be something like:

docker buildx build --source-ref v1.2.3 .
docker buildx build --source-ref 66735c67 .
docker buildx build --source-ref refs/heads/main .

The exact flag name is not important to me. The important behavior is that Buildx can resolve a ref in the local Git repository and use that committed tree as the build context.

Current behavior

Local directory contexts build from the current filesystem state. To build a different local commit today, I need to check out that commit before running docker buildx build.

Why this would be useful

This would make local Git builds more consistent with remote Git builds.

Some common cases where this would help:

• building multiple commits or tags from the same local clone
• testing a release tag without disturbing the current checkout
• building from a private local mirror without network access
• avoiding another remote clone when the repository already exists locally
• keeping CI scripts consistent between local and remote source modes
• reproducing historical builds from local repository data

Semantics

If a specific ref is requested, Buildx should build the committed tree at that ref, not the current working tree with uncommitted changes. That matches the reproducibility model users get with remote Git contexts.

If users want to include uncommitted local changes, the existing behavior would still be available:

docker buildx build .

Related issues

This is related to local Git metadata handling, but it is a different request:

• https://github.com/docker/buildx/issues/1290
• https://github.com/docker/buildx/issues/2784
• https://github.com/docker/buildx/issues/3855

Those issues are about collecting or exposing Git information from the current local checkout. This request is about choosing which local Git ref is used as the build source.

Start by tracing how Buildx handles local directory contexts and how remote Git contexts resolve branches, tags, commits, and checksums. Define the ref-selection behavior for a local repository, including committed-tree semantics and the existing uncommitted-work path; done means a local ref can be built without changing the current checkout.