Forum OpenACS Development: Vendor branch of OpenACS using Git?

As I mentioned back on 2023-10-18, I want to build a custom website based on OpenACS. I am (or at least used to be) intimately familiar with how to do that using a CVS vendor branch to import the stock OpenACS code. But I don't want to use CVS anymore, I want to use Git. Has anyone found a clear explanation of the best way to do this? I have looked, and tried certain things which I'll discuss below, but currently I'm not sure what the best approach is.

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 (fetch)
origin (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.