git-sync-filtered

A thin wrapper around git-filter-repo for syncing filtered commits from a private repository to a public repository.

Overview

git-sync-filtered clones a private repository, filters it to only include specified paths using git-filter-repo, and pushes the result to a public repository's sync branch. This enables maintaining a public subset of a private repository while preserving commit history.

Installation

uv (recommended)

uv tool install git-sync-filtered

pip

pip install git-sync-filtered

uvx (run without installing)

uvx git-sync-filtered \
  --private git@github.com:org/private.git \
  --public git@github.com:org/public.git \
  --keep src \
  --keep docs

GitHub Actions

You can use this workflow to sync from your private repo to a public repo when the private repo receives a push.

In your private repository, create .github/workflows/sync.yaml:

name: Sync to Public Repo

on:
  push:
    branches:
      - main

jobs:
  sync:
    uses: Merge-42/git-sync-filtered/.github/workflows/sync.yaml@v0.1.5
    with:
      private_repo: ${{ github.repositoryUrl }}
      public_repo: git@github.com:org/public.git
      keep: src docs
      merge: true
    secrets:
      GH_TOKEN: ${{ secrets.GH_PAT }}

Required secrets:

• GH_PAT - A GitHub Personal Access Token with repo scope (for pushing to the public repo)

Available inputs:

Usage

git-sync-filtered \
  --private git@github.com:org/private.git \
  --public git@github.com:org/public.git \
  --keep src \
  --keep docs

Using a paths file

Create a file with paths to keep (one per line, lines starting with # are comments):

src
docs
README.md

git-sync-filtered \
  --private git@github.com:org/private.git \
  --public git@github.com:org/public.git \
  --keep-from-file paths.txt

Options

How It Works

1. Clones the private repository
2. Runs git-filter-repo to filter to only the specified paths
3. Pushes filtered commits to the public repository's sync branch
4. Optionally merges the sync branch into main

The sync branch can then be merged into main manually or with --merge.

Workflow

flowchart LR
    A[Private Repo<br/>private-branch] -->|clone & filter| B[git-sync-filtered]
    B -->|push| C[Public Repo<br/>sync-branch]
    C -->|"merge<br/>(manual or with --merge)"| D[Public Repo<br/>main-branch]

Requirements

• Python 3.10+
• git >= 2.36.0

Sponsored by Merge 42