Re: [PATCH 1/2] git-subtree: Bail out if we find output from Rust rewrite [and 1 more messages]

From: Colin Stagner <ask+git@howdoi.land>
Date: Jul 15, 2026, 03:47 UTC
Message-ID: <b2e0142c-f8d3-442d-b3e7-63233ab88a17@howdoi.land>
In-Reply-To: <27216.58259.815175.923629@chiark.greenend.org.uk>

Nothing here impacts the patch under review, so this is a bit OT, but...

On 7/10/26 07:20, Ian Jackson wrote:

Show 13 quoted lines

> Colin Stagner writes ("Re: [PATCH 1/2] git-subtree: Bail out if we find output from Rust rewrite [and 1 more messages]"):
> 
>> git-subtree.sh doesn't really deal in "upstreams" in the git-branch or
>> git-merge sense.
> 
> I'm using "upstream" in the wider sense; here, when you import a
> depedency you're downstream of it.
>
> I want a term that talks about the logical (even, social) relationship
> between the two projects; and it should be one that makes sense from
> the point of view of the upstream.  Talking about the file position
> within the downstream tree doesn't make sense from the upstream's
> point of view.

It may be useful to differentiate between command documentation like git-merge(1) and tutorial documentation like gitworkflows(7).

The man page for `merge` reads like: "So you want to merge THIS into THAT? Here's how to do it." The banner-line example is merging a topic branch into master, but the "social" aspect of this is not front-and-center.

Other common terms used in merges include "ours" (HEAD) and "theirs" (MERGE_HEAD, "branch head," "commit [that is being merged]").

gitworkflows(7) discusses the social relationships of branches, including the "merge upwards" workflow. Here is where we find more social terms like "upstream" and "downstream:"

     The merge workflow works by copying branches between
     upstream and downstream. Upstream can merge
     contributions into the official history;
     downstream base their work on the official history.

But "upwards" or "upstream" is merely in the direction of increasing stability or acceptance. This makes the terms "upstream" and "downstream" very broad and inclusive. An upstream branch might be in the same repo, a parent repo of a fork, or an entirely different repo. The repo might be yours or belong to someone else.

Branches are branches, wherever they are.

Show 6 quoted lines

> I think the dependency relationship is inherent in git-subtree's usual
> use cases: suppose a project A gets merged with git-subtree into a
> subdirectory S of project B, so that B.git:/S/ is a copy of A.git:/
> 
> Then I think almost invariably, this is because A has B as a
> dependency.  And A has B as an upstream.

"Dependencies" are perhaps a bit beyond Git's usual scope as I understand it.

For subtree merges, it is possible that "largely unrelated" minirepos are being collected together just to make them a monorepo. I have also used subtree merges within a single repo. This is handy to keep a subproject isolated on its own branch for reuse elsewhere.

For splits, it's possible that history is split just to meet the needs of some other build system. I've observed this in the wild with AUR. I've seen multiple AUR packages stored together [1], but they must be `subtree split` first with aurpublish [2]. AUR users have been on-list before to report trouble with `subtree split` that I inadvertently caused [3]. They may be very interested in your rewrite.

In conclusion,

* Documentation is hard!

* Consider focusing "command-level" documentation more on mechanics. Use 
very specific terms like "branch," "(sub)tree," "merge-base," etc.

* Consider using "upstream" and "downstream" in the context of the 
"merging upwards" workflow from gitworkflows(7). It is not necessary for 
these to be in another repo or even a different "project."

These are just my recommendations, and they're not relevant for this patch series.

Show 6 quoted lines

>> I haven't tried it, but I think if --squash is in use, then attempting
>> an unmarked subtree merge will probably die with "unrelated history"
>> warnings.
> 
> I think that's not guaranteed if squash merges and non-squash merges
> are interleaved.

Probably true.

Colin

[1]: https://github.com/christian-heusel/aur

[2]: https://github.com/eli-schwartz/aurpublish

[3]: <755578cb-07e0-4b40-aa90-aacf4d45ccaa@heusel.eu>