How To Move Subdirectory Into Separate Git Repository?

When working with large monolithic Git repositories, teams often find that separating parts of the codebase into distinct repositories can improve maintainability and focus. This article explains How To Move Subdirectory Into Separate Git Repository while preserving its history.

Steps To Move Subdirectory

Step 1. Extract the Subdirectory

First, we need to filter out the history of the subdirectory to be moved. This can be accomplished with git filter-repo, which is more modern and efficient than the older git filter-branch command.

Follow these steps:

1. Install git-filter-repo

If git-filter-repo is not installed, you can install it via pip:

pip install git-filter-repo

2. Filter the Repository

Let's say we have a repository with the following structure:

my-repo/
├── .git
├── subdir/
│   ├── file1.txt
│   └── file2.txt
└── other-dir/
    └── file3.txt

To extract the subdir into its own repository:

1. Clone the repository (if you don’t already have a working copy):

git clone https://github.com/username/my-repo.git
cd my-repo

2. Use git-filter-repo to filter the subdir:

git filter-repo --path subdir --path-rename subdir:.

Here, --path subdir tells Git to keep only the history for subdir, and --path-rename subdir:. renames the subdir path to the root (.) of the repository.

Note: This command will alter the repository in place. If you want to keep the original repository unchanged, use a separate clone.

Step 2. Create the New Repository

Now, we will create a new repository to host the subdir content.

1. Go to the directory where you want to create the new repository:

cd ..
mkdir new-repo
cd new-repo

2. Initialize the new repository:

git init

3. Add the Subdirectory's Content

Next, we need to move the filtered content from the original repository to the new one.

1. Copy the .git directory from the filtered repository to the new repository:

cp -r ../my-repo/.git .

2. Reset the working directory to match the history:

git reset --hard

This makes the current working directory reflect the state of the subdir from the original repository's history.

3. Clean up the original repository (if necessary):

rm -rf ../my-repo

4. Push to Remote (if needed)

If you want to push this new repository to a remote server (e.g., GitHub), follow these steps:

1. Add a remote repository:

git remote add origin https://github.com/username/new-repo.git

2. Push the changes:

git push -u origin master

Optional: Update Submodules in the Original Repository

If you want the original repository to use the new repository as a submodule:

1. In the original repository, remove the old subdirectory:

rm -rf subdir

2. Add the new repository as a submodule:

git submodule add https://github.com/username/new-repo.git subdir
git submodule init
git submodule update

Conclusion

Moving a subdirectory to a new Git repository can help streamline project management and development processes. By using git-filter-repo, you can extract and preserve the history of the subdirectory, ensuring continuity. Always back up your data before performing such operations to safeguard against potential mishaps.