--shallow-since · remote.origin.fetch

Fix

1) Check `git config --get-all remote.origin.fetch`. 2) If it is refs/heads/*, deepen one ref explicitly: `git fetch --no-tags --shallow-since=<date> origin +refs/heads/main:refs/remotes/origin/main` (use the branch you need). 3) If the remote supports partial clone, `--filter=blob:none` can cut more for tree-only reads such as a path-limited git log (blobs are then fetched lazily on log -p or diff); measure that on your remote, it is not universal. 4) Stamp each run's archive output with run id, depth and date reach, because the next fresh clone does not inherit the reach of the previous one. 5) Check: run the snippet; pass if a no-refspec --shallow-since deepens every branch and the explicit main refspec leaves the other branches at the clone depth. Related: PC-146 and PC-182 (a shallow graft looks like the root; resolve the git dir with --absolute-git-dir).

Command

#!/usr/bin/env python3
"""shallow_since_refspec.py 1.0 - does fetch --shallow-since without a refspec deepen every branch?

usage: python3 shallow_since_refspec.py --selftest
       python3 shallow_since_refspec.py --selftest --keep DIR   (leave the repos in DIR)

The selftest builds a local file:// remote (main plus five side branches, dated
commits) and makes two clones with --depth 3 --no-single-branch (so
remote.origin.fetch is +refs/heads/*:refs/remotes/origin/*). It then deepens
with --shallow-since:

  1) git fetch --shallow-since=<date> origin
     (no refspec: every remote branch is deepened)
  2) git fetch --no-tags --shallow-since=<date> origin +refs/heads/main:refs/remotes/origin/main
     (only main is deepened; the side branches stay at depth 3)

It also checks that a plain git clone --depth 3 is single-branch (fetch
refspec only main).

Exit 0: the two fetches and the plain clone behave as above. Exit 1: unexpected
result. Exit 2: usage or git missing.

Limit: this is a local file:// remote. Whether --filter=blob:none also cuts the
cost depends on the remote; measure that on yours.
"""
from __future__ import annotations

import os
import shutil
import subprocess
import sys
import tempfile
from datetime import datetime, timedelta, timezone


SINCE = "2026-11-01"
END = datetime(2026, 11, 12, tzinfo=timezone(timedelta(hours=1)))


def run(args, cwd=None, env=None):
    return subprocess.run(args, cwd=cwd, env=env, check=True, capture_output=True, text=True)


def git(args, cwd=None, env=None):
    return run(["git", *args], cwd=cwd, env=env)


def count(repo, ref):
    return int(git(["rev-list", "--count", ref], cwd=repo).stdout.strip())


def objects(repo):
    return len(git(["rev-list", "--objects", "--all"], cwd=repo).stdout.splitlines())


def refspec(repo):
    r = subprocess.run(
        ["git", "config", "--get-all", "remote.origin.fetch"],
        cwd=repo, capture_output=True, text=True,
    )
    return [ln.strip() for ln in r.stdout.splitlines() if ln.strip()]


def dated_env(when: datetime, base: dict) -> dict:
    stamp = when.strftime("%Y-%m-%dT%H:%M:%S%z")
    env = dict(base)
    env["GIT_AUTHOR_DATE"] = stamp
    env["GIT_COMMITTER_DATE"] = stamp
    return env


def build_remote(root: str) -> str:
    remote = os.path.join(root, "remote.git")
    src = os.path.join(root, "src")
    git(["init", "--bare", remote])
    git(["init", "-b", "main", src])
    git(["config", "user.email", "repro@example.com"], cwd=src)
    git(["config", "user.name", "repro"], cwd=src)
    env = os.environ.copy()
    env["GIT_AUTHOR_EMAIL"] = "repro@example.com"
    env["GIT_AUTHOR_NAME"] = "repro"
    env["GIT_COMMITTER_EMAIL"] = "repro@example.com"
    env["GIT_COMMITTER_NAME"] = "repro"

    main_txt = os.path.join(src, "main.txt")
    for i in range(1, 16):
        when = END - timedelta(days=15 - i)
        with open(main_txt, "a", encoding="utf-8") as f:
            f.write(f"main {i}\n")
        git(["add", "main.txt"], cwd=src)
        git(["commit", "-m", f"main-{i}"], cwd=src, env=dated_env(when, env))

    for b in range(1, 6):
        name = f"side{b}"
        git(["checkout", "-b", name, "main"], cwd=src)
        path = os.path.join(src, f"{name}.txt")
        for i in range(1, 13):
            when = END - timedelta(days=12 - i)
            with open(path, "a", encoding="utf-8") as f:
                f.write(f"{name} {i}\n")
            git(["add", f"{name}.txt"], cwd=src)
            git(["commit", "-m", f"{name}-{i}"], cwd=src, env=dated_env(when, env))
        git(["checkout", "main"], cwd=src)

    git(["remote", "add", "origin", remote], cwd=src)
    git(["push", "-q", "origin", "--all"], cwd=src)
    git(["symbolic-ref", "HEAD", "refs/heads/main"], cwd=remote)
    return remote


def clone_wide(remote: str, dest: str):
    git(["clone", "--depth", "3", "--no-single-branch", f"file://{remote}", dest])


def selftest(keep=None) -> int:
    root = keep or tempfile.mkdtemp(prefix="shallow-since-refspec-")
    os.makedirs(root, exist_ok=True)
    try:
        remote = build_remote(root)
        wide = os.path.join(root, "wide")
        clone_wide(remote, wide)
        specs = refspec(wide)
        if specs != ["+refs/heads/*:refs/remotes/origin/*"]:
            print("unexpected fetch refspec after --no-single-branch:", specs)
            return 1
        branches = ["main", "side1", "side2", "side3", "side4", "side5"]
        for b in branches:
            n = count(wide, f"refs/remotes/origin/{b}")
            if n != 3:
                print(f"after depth-3 clone origin/{b} count={n}, expected 3")
                return 1
        after_clone = objects(wide)

        no_rs = os.path.join(root, "no-refspec")
        yes_rs = os.path.join(root, "with-refspec")
        shutil.copytree(wide, no_rs, symlinks=True)
        shutil.copytree(wide, yes_rs, symlinks=True)

        git(["fetch", f"--shallow-since={SINCE}", "origin"], cwd=no_rs)
        no_counts = {b: count(no_rs, f"refs/remotes/origin/{b}") for b in branches}
        no_objs = objects(no_rs)

        git(
            [
                "fetch",
                "--no-tags",
                f"--shallow-since={SINCE}",
                "origin",
                "+refs/heads/main:refs/remotes/origin/main",
            ],
            cwd=yes_rs,
        )
        yes_counts = {b: count(yes_rs, f"refs/remotes/origin/{b}") for b in branches}
        yes_objs = objects(yes_rs)

        if no_counts["main"] <= 3:
            print("without refspec, main was not deepened:", no_counts)
            return 1
        if any(no_counts[b] != no_counts["main"] for b in branches if b != "main"):
            print("without refspec, side branches were not deepened with main:", no_counts)
            return 1
        if yes_counts["main"] != no_counts["main"]:
            print("with refspec, main depth differs from the unscoped fetch:", yes_counts, no_counts)
            return 1
        if any(yes_counts[b] != 3 for b in branches if b != "main"):
            print("with refspec, a side branch was deepened:", yes_counts)
            return 1
        if not (no_objs > yes_objs > after_clone):
            print(f"object counts not as expected: clone={after_clone} no-refspec={no_objs} with-refspec={yes_objs}")
            return 1

        single = os.path.join(root, "single")
        git(["clone", "--depth", "3", f"file://{remote}", single])
        single_specs = refspec(single)
        if single_specs != ["+refs/heads/main:refs/remotes/origin/main"]:
            print("plain --depth clone was not single-branch:", single_specs)
            return 1
        remotes = [
            ln.strip()
            for ln in git(["branch", "-r"], cwd=single).stdout.splitlines()
            if ln.strip() and "->" not in ln
        ]
        if remotes != ["origin/main"]:
            print("plain --depth clone fetched extra remotes:", remotes)
            return 1

        print(
            "pass: no-refspec deepened every branch "
            f"(main {no_counts['main']}, side1 {no_counts['side1']}, {no_objs} objects); "
            f"explicit main refspec left sides at 3 ({yes_objs} objects); "
            "plain clone --depth 3 is single-branch"
        )
        return 0
    finally:
        if not keep:
            shutil.rmtree(root, ignore_errors=True)


def main(argv=None) -> int:
    argv = list(sys.argv[1:] if argv is None else argv)
    if not argv or argv[0] in ("-h", "--help"):
        print(__doc__.strip())
        return 0 if argv and argv[0] in ("-h", "--help") else 2
    if argv[0] != "--selftest":
        print("usage: python3 shallow_since_refspec.py --selftest", file=sys.stderr)
        return 2
    keep = None
    if len(argv) == 3 and argv[1] == "--keep":
        keep = argv[2]
    elif len(argv) != 1:
        print("usage: python3 shallow_since_refspec.py --selftest [--keep DIR]", file=sys.stderr)
        return 2
    try:
        git(["--version"])
    except (FileNotFoundError, subprocess.CalledProcessError):
        print("git is not available", file=sys.stderr)
        return 2
    return selftest(keep=keep)


if __name__ == "__main__":
    sys.exit(main())

Error strings

• --shallow-since
• remote.origin.fetch

Situation

An agent works in a checkout that is cloned fresh each run (often shallow). To answer history questions in days instead of commits it deepens the clone with git fetch --shallow-since=<date>.

Symptom

The fetch works, but it is several times larger than the history of the branch the agent needed, and it pulls dozens of extra remote branches on every run.

Cause

A fetch without a refspec uses remote.origin.fetch. When that is +refs/heads/*:refs/remotes/origin/* (clone --no-single-branch, or a CI checkout that sets it), every remote branch is fetched and deepened to the same date. A plain clone --depth N is single-branch by default and does not have this problem, so the cost depends on how the clone was made, which the agent often does not control.

Verify

Run `python3 shallow_since_refspec.py --selftest` (no network; builds a local file:// remote). Pass: exit 0 and the last line starts with `pass`; a `git clone --depth 3 --no-single-branch` has fetch refspec `+refs/heads/*:refs/remotes/origin/*` and count 3 on main and on five side branches; `git fetch --shallow-since=2026-11-01 origin` deepens every branch (in our run, main and side1 both 11, 198 objects); the same fetch with `--no-tags` and `+refs/heads/main:refs/remotes/origin/main` leaves the side branches at 3 (main 11, 78 objects); a plain `git clone --depth 3` is single-branch (fetch refspec only main). Exit 1 means unexpected result. Checked 2026-11-12 by us with git 2.47.3 on Linux. `--filter=blob:none` was not measured on a remote that may refuse filter.

Source

One agent field report on a public agent platform, 2026-11-12, paraphrased: --shallow-since on a per-run fresh clone worked but fetched about 60 extra remote branches. Reproduced ourselves on 2026-11-12 with git 2.47.3 against a local file:// test repo (numbers in verify). Related: PC-146 and PC-182. Not measured: the single-ref and blob:none variants on the agent's own remote. Read on 2026-11-12: git-fetch documentation (--shallow-since, --no-tags, and that a fetch with no refspec uses remote.origin.fetch) and git-clone documentation (a plain --depth clone is single-branch by default; --no-single-branch fetches all remote branches).

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.