How to vendor a git repo¶

By “vendoring a repo” we mean to include the source code and history of one git repo into another, already existing, git repo. Following this how to will give you one repo with an extra root.

The TARGET repo is the the repo we want to end up with while the ORIGIN repo is the one we want to merge in (our terms). In this case, we wish to merge the “main” branch of ORIGIN into the “master” branch of TARGET. (It is easier to keep track if the branches have different names.)

This how-to assumes that ORIGIN and TARGET has no shared history, as is the case if ORIGIN is a standalone library or django app.

Prep the ORIGIN repo¶

Be placed somewhere there is no git repo
Clone the ORIGIN repo locally:
```
git clone ORIGIN-clone path/to/ORIGIN
```
cd into ORIGIN-clone
Make sure you are on “main” branch of ORIGIN-clone
Move every single file tracked by git (and not ignored by .gitignore) in ORIGIN to a new directory that does not exist on TARGET, we’ll standardize on merge/ here:
```
mkdir merge
git mv -k * merge/
```
Without the -k-flag, git mv would error out with fatal: can not move directory into itself, source=merge, destination=merge/merge and refuse to do anything.

Finally move the hidden files (filenames that start with “.”):
```
git mv -k .* merge/
```
Everything should now be in merge/ except for the magic directory .git/, any files hidden by .gitignore, and any untracked files. This is as it should be.

Commit:

git commit -m 'Move repo contents into subdirectory'

Add the TARGET repo as a remote to the ORIGIN-clone:
```
git remote add TARGET path/to/TARGET
```
Fetch the TARGET repo into the ORIGIN-clone repo:
```
git fetch TARGET
```
Merge ORIGIN-clone’s “main” into feceiving’s “master”:
```
git merge --allow-unrelated-histories TARGET/master
```
Note the --allow-unrelated-histories-flag.
Push the “master”/”main” of the ORIGIN-clone to a temporary branch on TARGET:
```
git push -u TARGET merge-ORIGIN
```

You’re finished with the ORIGIN-clone. You may remove it if you like.

Fix up the TARGET repo¶

Switch to a local clone of the TARGET repo
Checkout and pull the temporary branch:
```
git checkout -b merge-ORIGIN
git pull
```
You can either merge to “master” now (recommended) or start a new branch off merge-ORIGIN for the fixing-up. The goal is to have two different branches: one that is a clean copy of ORIGIN’s history, one that does all the fixing. This makes the latter easy to review and safer to do in general.
Whether you merged to “master” or not, start a new branch for the fixing:
```
git switch -c move-ORIGIN-files-to-correct-location
```
Do all the moving. Remember that ORIGIN’s code might have additional stuff in it’s .gitignore and other files (inside merge/) that needs to be added to the corresponding files of TARGET. Make one commit for all files that can be moved without changes and then commit each time you need to merge in new stuff. If you need to update import paths or file paths in either, they also get a commit each, per path. So: if ORIGIN’s module name is “my_fine_app” and it will be moved to TARGET’s file hierarchy as “src/argus/my_fine_app” and module hierarchy as “argus.my_fine_app”, make one commit for all the file path changes and another for all the “import” changes.
Push move-ORIGIN-files-to-correct-location upstream so others can have a look:
```
git push -u move-ORIGIN-files-to-correct-location
```
When done and tests are green, merge/rebase/squash to “master” (you can do this via github).

Done!

If ORIGIN is to cease to exist as a repo, move its open issues to TARGET’s issue tracker.

Transferring Github issues¶

It is easy to transfer issues between Github repos, though only one at a time. There’s a link to transfer issues in the right-hand menu on each issue page. If the TARGET repo has the labels of the ORIGIN repo, the labels will copy over just fine too.

Notifications will be sent per issue moved so if many are moved at a time give a heads up to the team: they are about to be spammed.

Move Github PR¶

If you want to move a PR to the TARGET’s official Github you first need to move the branch, then start a new PR with the same name at TARGET, then link back to the ORIGIN repo from the new PR. Now you can close the PR in ORIGIN.

Move other branches from ORIGIN to TARGET¶

Prep code in ORIGIN¶

In your local copy of ORIGIN (or a new clone) make a branch off “main” called rename:

git switch -c rename

Move the code of “main” (just the code) to the paths that are correct for TARGET. Feel free to also update import paths and template paths in this code. Commit the changes to the rename branch.

If the code is going into a new subdirectory, make sure the parent directory is empty. If necessary git rm the __init__.py file or any others.

Setup the remote in the ORIGIN repo¶

Add the TARGET repo as a remote:
```
git remote add TARGET url/to/TARGET
```
Fetch the branches on argus:
```
git fetch TARGET
```
Checkout “master”:
```
git switch master
```

Move the actual branch¶

First move your branch onto the rename branch.

Do git mv old new or git rebase rename mybranch or use a graphical client to cherry-pick one by one onto “main”, or copy the files to the correct place and add+commit them as new. It is enough to just move the files. Correcting import paths and file include paths can be done after the move, in the new repo, with a new commit.

This way, you can deal with file renaming conflicts once, and content change conflicts once.

Now you’re ready for the move.

Make a temporary branch name for the branch you want to move, at its head:
```
git switch mybranch
git switch -c fvgyhj
```
If it’s only a single commit you can cherry-pick it. Move the real name to the “master” then cherry-pick:
```
git branch -f mybranch master
git switch mybranch
git cherry-pick fvgyhj
```
If not, a rebase can do it for you. If you didn’t do step 1 correctly there will be more conflicts than necessary!

How to rebase (assumes mybranch is rebased on rename):
```
git rebase --onto master rename mybranch
```
You can now remove the temporary branch:
```
git branch -d fvgyhj
```
Push the branch to the new remote:
```
git switch mybranch
git push TARGET
```

Make a new PR¶

Make the PR in TARGET’s repo and pull the branch in your local copy of that repo.
Do any internal changes to the actual code in the new repo if you didn’t do that as a part of the branch prep.