Subdirectory to Submodule

Goal: Split a subfolder (e.g. a Python package) from an existing (Go) project into a standalone repository with a fully preserved commit history.

This documents how I split ytx into a separate fastapi project.

Prerequisites

Install git-filter-repo:

brew install git-filter-repo   # macOS or
pip install git-filter-repo    # cross-platform

Steps

Clone the Original

git clone https://github.com/desertthunder/ytx.git
cd ytm

Filter the history to only include the subdirectory

git filter-repo --path music --force
git mv music/**/* ./
git commit -m "unwrap repo"

This rewrites history so only commits touching that folder remain.

Push

git remote add origin git@github.com:desertthunder/ytm.git
git push -u origin main

Linking Back

In the original project:

cd ytx # clone ytx
git rm -r --cached music
rm -rf music
git submodule add git@github.com:desertthunder/ytm.git music
git commit -m "Add Python package as submodule"