Extracting a Subdirectory

Learn how to extract a subdirectory from a repository while preserving its history

One of the most common uses of git-filter-repo is extracting a subdirectory from a repository to create a standalone project or prepare it for merging into another repository.

Basic Extraction

To extract a single directory and make it the root of your repository:

1. Clone the repository

   Start with a fresh clone of your repository:

   git clone https://github.com/example/repo.git
   cd repo
   

   git-filter-repo requires a fresh clone as a safety measure. Use --force to override this requirement if absolutely necessary.

2. Extract the subdirectory

   Use the --subdirectory-filter option to extract a directory:

   git filter-repo --subdirectory-filter src/
   

   This will:

   • Keep only files under src/
   • Move src/ contents to the repository root
   • Remove commits that only touched files outside src/
3. Verify the results

   Check that the extraction worked correctly:

   git log --oneline
   ls -la
   

Extract and Rename to Subdirectory

For merging into another repository, you may want to extract a directory but place it under a new path:

git filter-repo --path src/ --to-subdirectory-filter my-module

This command:

• Extracts only the src/ directory
• Places it under my-module/src/ in the filtered repository
• Preserves the full history

Advanced: Extract and Rename

Extract a specific subdirectory and rename it to a different path:

git filter-repo \
    --path src/some-folder/some-feature/ \
    --path-rename src/some-folder/some-feature/:src/

This keeps src/some-folder/some-feature/ but renames it to src/.

Complete Example: Prepare for Merging

When preparing a subdirectory to merge into another repository:

1. Extract and reorganize

   git filter-repo \
       --path src/ \
       --to-subdirectory-filter my-module \
       --tag-rename '':'my-module-'
   

   This command:

   • Extracts the src/ directory
   • Moves it to my-module/src/
   • Prefixes all tags with my-module- to avoid conflicts
2. Add the remote

   cd ../target-repo
   git remote add extracted-module ../repo
   git fetch extracted-module
   
3. Merge the history

   git merge --allow-unrelated-histories extracted-module/main
   

Always work on a fresh clone. git-filter-repo rewrites history and will remove your remote configuration to prevent accidental pushes.

Extracting Multiple Paths

To extract multiple directories or files:

git filter-repo \
    --path dir1/ \
    --path dir2/ \
    --path important-file.txt

All specified paths will be retained while everything else is removed.