gitsplit

Description

This tool is used to split parts of a repository into a new repository. The tool must be executed inside the source repository, but does not modify the source repository (make sure to read the disclaimer). The tool tries to determine file renames and keep history across renames accordingly.

Requirements

The script prefers git filter-repo (the modern, officially recommended replacement for git filter-branch) and falls back to git filter-branch if git filter-repo is not available.

Installing git filter-repo (recommended)

# via pip
pip install git-filter-repo

# via Homebrew (macOS)
brew install git-filter-repo

# via package manager (Debian/Ubuntu)
sudo apt install git-filter-repo

See https://github.com/newren/git-filter-repo for more installation options.

Fallback: git filter-branch

git filter-branch is still supported as a fallback. It has been deprecated since Git 2.24 but remains functional. The script suppresses the deprecation warning automatically via FILTER_BRANCH_SQUELCH_WARNING=1.

Usage

usage: gitsplit branch dst [keep [keep ...]]

DESCRIPTION
    This tool is used to split parts of a repository into a new
    repository. The tool must be executed inside the source re-
    pository. The specified destination path cannot be a sub-
    directory of the source repository.

ARGUMENTS
    branch    The source branch to split from.

    dst       The destination path for the repository to create.
              This path must not exist.

    keep      One path or multiple paths to keep in the new repository.
              If no paths are specified the entire source branch is
              split into a new repository.

Example

# Split the 'src/mymodule' directory and a single file from 'main' branch
# into a new repository at '../new-repo'
cd /path/to/source-repo
gitsplit main ../new-repo src/mymodule README.md

Changes from the original 2018 version

• git filter-repo support: The script now uses git filter-repo as the primary filter tool when available. This is the officially recommended replacement for git filter-branch and is significantly faster and more reliable, especially for large repositories.
• git filter-branch fallback: When git filter-repo is not installed, the script falls back to git filter-branch with FILTER_BRANCH_SQUELCH_WARNING=1 to suppress the deprecation warning that would otherwise interfere with the script.
• Fixed xargs empty-input bug: git remote | xargs git remote rm and git tag -l | xargs git tag -d would fail when there were no remotes or tags. These are now handled with explicit loops.
• Fixed rename-tracking: The previous git log --follow --name-status --oneline approach mixed commit-message lines with file-status lines, causing incorrect array indexing. The new approach uses --diff-filter=R --format="" to emit only rename lines, parsed correctly with tab-separated fields.
• Iterative rename chain following: Renames are now followed transitively (A→B→C), so the full rename history is preserved.
• Safer path handling: Paths are normalized without a Perl dependency. Destination path resolution no longer fails when the parent directory does not yet exist.
• Branch existence check: The script now verifies that the specified branch exists before proceeding.
• set -euo pipefail: The script now exits immediately on errors, unbound variables, or pipe failures.
• Automatic cleanup: A trap handler ensures the temporary directory is always removed, even if the script is interrupted.
• --no-local clone flag: Ensures a proper clone (with full object copying) rather than a hardlink-based local clone, which is important for subsequent filter-repo/filter-branch operations.

Disclaimer

Use with caution. This software may contain serious bugs. I can not be made responsible for any damage the software may cause to your system or files. Make sure to backup your source repository before using this tool.

License

gitsplit

Copyright (C) 2018-present by Harald Lapp harald@octris.org

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.