Add optional per-mirror upstream history mode

[realityforge]

Summary

Today Braid vendors upstream content by flattening the selected upstream tree into the downstream repository. This keeps downstream history simple: each braid add or braid pull produces a normal downstream commit, and .braids.json records the upstream revision.

That model is easy to reason about, but it loses useful local history. After pulling an upstream update, git log and git blame inside the downstream repository do not naturally know about the upstream commits that produced the vendored files.

It would be useful to support an optional per-mirror mode that imports upstream history locally.

Proposed behavior

History mode should be chosen when the mirror is added.

braid add <upstream-url> vendor/lib --history

Braid would record that choice in .braids.json for that mirror. Future braid pull vendor/lib commands would continue using history mode automatically for that mirror.

Mirrors added without history would keep the current flattened behavior.

What this could mean

There are two main strategies, with different tradeoffs.

Option 1: raw upstream history merge

Braid could make the downstream add or update commit a real merge commit, with parents:

1. the current downstream HEAD
2. the upstream revision being added or pulled

This would preserve original upstream commit SHAs and make the upstream history reachable from the downstream repository.

The major downside is that Git commits are whole-repository snapshots. If we merge the raw upstream revision, we do not get only the braided path history. We get the upstream commit and its reachable ancestors as full upstream repository history.

Pros:

• Preserves original upstream SHAs.
• Conceptually simple.
• Makes upstream commits reachable locally.
• Easier to inspect exact upstream provenance.

Cons:

• Imports the entire upstream repository history, not just the mirrored path.
• Can significantly increase downstream repository size.
• git log may become noisier.
• The upstream tree root does not match the downstream mirror path, so path-aware history may be less useful than expected.

Option 2: filtered or synthetic path history

Braid could rewrite upstream history so that only the braided path is preserved, placed at the downstream mirror path.

For example, upstream history for src/lib could become synthetic commits affecting vendor/lib in the downstream repository.

Pros:

• Gives useful path-shaped local history.
• Avoids importing unrelated upstream files and commits.
• Better fit for git log -- vendor/lib and git blame vendor/lib/file.

Cons:

• Rewrites commits, so original upstream SHAs are not preserved as commit IDs.
• Requires a mapping from original upstream SHAs to synthetic downstream SHAs.
• More complex to implement and cache correctly.
• Needs clear behavior when the upstream path is renamed, deleted, or filtered through history.

Suggested direction

Keep the current flattened behavior as the default.

Add history as an explicit per-mirror setting selected during braid add. Once enabled for a mirror, braid pull should continue preserving history for that mirror without requiring a repeated flag.

Raw history is simpler and preserves original SHAs, but it imports much more than users may expect. Synthetic history is more useful for day-to-day log and blame, but it is a larger feature and needs careful SHA mapping.

[realityforge]

At the moment the juice is not worth the squeeze but if we ever have a real need for this it is posisble...