Forum OpenACS Development: Vendor branch of OpenACS using Git?
I intend to have just one large Git project (a "monorepo"), with everything in sub-directories. One of my sub-directories is "openacs", which will be my website code.
There are several Git tools and extensions intended to help with this sort of thing. The Git subtree command is included with Git. Git vendor is annother extension layered on top of Git subtree, highly recommended by some. git-subrepo is yet another such extension.
Git subtree gives you the choice of importing the entire
vendor Git history, or of suppressing it with --squash.
Git vendor and subrepo both seem
to always use --squash, no matter what. Since
Git is a distributed version control system, my original plan was
to never use --squash. If I can easily see the
upstream OpenACS history on my vendor branch, that's good, I
definitely want that, right? In theory, yes. With the way Git
subtree works in practice, I'm beginning to see why most
people seem to use --squash.
I found two helpful articles, Vendor branch in a git monorepo by David Röthlisberger (2022-10-04), and Mastering Git subtrees by Christophe Porteneuve (2015-02-02).
Röthlisberger's article starts by showing how to use Git to manually to do a CVS-style vendor branch. That seems clear enough that I'm somewhat tempted to actually do it that way! (However, I'm not sure how well his manual example would extend to importing the full vendor Git history, instead of just a CVS-style release tarball.) Here's where things seem to get wonky though... After finishing discussion of the manual approach, Röthlisberger states:
git subtree does exactly what I have described above, except that the code on the “vendor” branch comes from another git repo instead of a tarball, and the code on the “vendor” branch isn’t under the third_party/curl/ directory. Instead, git subtree moves the code to third_party/curl/ when merging it to our main branch.
Note that "Instead" above! He does not discuss it further, and I don't understand yet what the "moves the code" part really means. But a key distinction seems to that with Git subtree, there is no actual branch for the "vendor branch"!
In my simple Git subtree example below (which does not
use --squash), at the end I still only have one branch,
the "master" my own project started with. I do not know if there is
some sort of subtree-specific vendor branch hidden somewhere, but I
definitely don't see any new branches.
cd my-project-dir git subtree add --prefix=openacs /home/vc-root/git-pub/openacs/openacs-core.git oacs-5-10 git subtree add --prefix=openacs/packages/xotcl-core /home/vc-root/git-pub/openacs/xotcl-core.git oacs-5-10 git subtree add --prefix=openacs/packages/ref-currency /home/vc-root/git-pub/openacs/ref-currency.git main $ git branch --list * master
Note that above, my /home/vc-root/git-pub/ just holds
local bare repository clones of the upstream OpenACS repositories, so
I can experiment without repeatedly fetching from Github. E.g. I have
this:
$ cd /home/vc-root/git-pub/openacs/openacs-core.git/ $ git remote -v origin git@github.com:openacs/openacs-core.git (fetch) origin git@github.com:openacs/openacs-core.git (push)
After doing my git subtree add commands above, all the
upstream OpenACS commits are now part of my master branch, and there
is no obvious way to filter them out, nor even to see them by
themselves without my local commits. A Git guru could
probably construct a git log incantation to separately
show just my local vs. the upstream OpenACS history, but I
don't know how to do that. This all seems much messier than I was
hoping.
Thus currently I plan to use --squash after all, which
should give me a CVS-like single commit for the entire vendor branch
import (the git subtree add command). When I want to
browse the upstream OpenACS history, I can always just go over to my
local clone and do it there, of course.
Next I should try to better understand what Git subtree is really doing underneath, and then better evaluate whether the subtree, vendor, or subrepo commands are better for the sort of vendor branching I want to do.
