Move a RYS repository with its history¶

Move a RYS (or gem) from its own repository into a subdirectory of another repository, for example gems/ryspec, keeping its commit history.

The procedure:

Rewrite the source repository so its files live under the target subdirectory.
Fetch the rewritten history into the destination repository.
Merge the histories.

Prerequisites¶

You need git-filter-repo installed (brew install git-filter-repo on macOS), and:

the source repository URL,
a clean temporary directory for the rewritten clone,
a target path in the destination repository, for example gems/ryspec.

Migration procedure¶

1. Clone the source repository into a temporary directory¶

git clone <ryspec_repo> ryspec_tmp
cd ryspec_tmp

2. Rewrite the repository into the target subdirectory¶

git filter-repo --to-subdirectory-filter gems/ryspec

After this step, every commit from the source repository is preserved, but its files are now stored under gems/ryspec.

3. Switch to the destination repository and create a working branch¶

cd ../your_app
git checkout -b fix/ryspec_history

4. Add the rewritten repository as a temporary remote¶

git remote add ryspec_clean ../ryspec_tmp
git fetch ryspec_clean

5. Remove the existing subtree if it is already present¶

If the target directory already exists and contains the old broken subtree, remove it first:

git rm -r gems/ryspec
git commit -m "chore: remove broken ryspec subtree"

Skip this step if gems/ryspec is not present yet.

6. Merge the rewritten history into the destination repository¶

git merge ryspec_clean/master --allow-unrelated-histories

This creates a merge commit connecting both repositories and keeps the full history of the moved RYS. Resolve any conflicts as usual, then finish the merge.

Full example¶

git clone <ryspec_repo> ryspec_tmp
cd ryspec_tmp
git filter-repo --to-subdirectory-filter gems/ryspec

cd ../your_app
git checkout -b fix/ryspec_history
git remote add ryspec_clean ../ryspec_tmp
git fetch ryspec_clean
git rm -r gems/ryspec   # if subtree already added
git commit -m "chore: remove broken ryspec subtree"
git merge ryspec_clean/master --allow-unrelated-histories

Verification¶

After the merge, verify that history was preserved:

git log -- gems/ryspec

The log shows commits from the old repository.

Cleanup¶

Remove the temporary remote, and the temporary clone ryspec_tmp if you no longer need it:

git remote remove ryspec_clean

Notes¶

git filter-repo rewrites commit hashes in the temporary clone.
Always run git filter-repo on a disposable clone, not on your original working repository.
If the default branch of the source repository is not master, merge the correct branch instead.