> ## Documentation Index
> Fetch the complete documentation index at: https://newren-git-filter-repo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Output and Control Options

> Options for controlling where filtering occurs, output behavior, and operational modes

# Output and Control Options

Options that control where git-filter-repo reads from and writes to, plus general operational controls.

## Location Options

### --source

**--source** `string`

Git repository to read from.

**Type:** Path to git repository

**Default:** Current directory (`.`)

**Effect:** Implies `--partial`

Specifies a different repository to read history from. When used with `--target`, allows filtering from one repository into another without mixing old and new history.

**Example:**

```bash theme={null}
git filter-repo --source /path/to/source-repo --target /path/to/new-repo
```

> [!NOTE]
>
> Using `--source` automatically enables `--partial` mode.

### --target

**--target** `string`

Git repository to overwrite with filtered history.

**Type:** Path to git repository

**Default:** Current directory (`.`)

**Effect:** Implies `--partial`

Specifies a different repository to write filtered history to. The target repository will be overwritten with the filtered history.

**Example:**

```bash theme={null}
git filter-repo --source ./old-repo --target ./new-repo --path src/
```

> [!WARNING]
>
> The target repository will be completely overwritten. Make sure you have backups.

## Operational Mode Options

### --force, -f

**--force** `boolean` (default: false)

Bypass fresh clone checks and rewrite history anyway.

**Aliases:** `-f`

**Warning:** History rewriting is IRREVERSIBLE

By default, git-filter-repo checks if the repository is a fresh clone to prevent accidental data loss. This flag bypasses those safety checks.

**When to use:**

* You're certain you have backups
* Repository fails fresh clone checks but you want to proceed anyway
* You're running git-filter-repo multiple times on the same repo

**Example:**

```bash theme={null}
git filter-repo --path src/ --force
```

> [!WARNING]
>
> **DO NOT** use `--force` habitually. Always work in a fresh clone when possible. If you need `--force`, make absolutely sure you have backups.

### --partial

**--partial** `boolean` (default: false)

Perform partial history rewrite, mixing old and new history.

**Effects:**

* Disables `refs/remotes/origin/*` → `refs/heads/*` migration
* Disables removal of `origin` remote
* Disables removal of unexported refs
* Disables reflog expiration
* Disables automatic `git gc`
* Changes `--tag-rename` and `--refname-callback` to create new refs instead of replacing

**Automatically enabled by:**

* `--source`
* `--target`
* `--refs`

**Example:**

```bash theme={null}
git filter-repo --path src/ --partial
```

> [!WARNING]
>
> Partial rewrites mix old and new history. Use with caution as this can lead to confusion.

### --refs

**--refs** `string[]`

Limit history rewriting to specified refs.

**Type:** One or more ref specifications

**Effect:** Implies `--partial`

**Format:** Same as `git fast-export` (ref names, ranges, globs)

Only the specified refs will be rewritten. All other refs remain unchanged.

**Examples:**

```bash theme={null}
# Rewrite only main branch
git filter-repo --refs refs/heads/main

# Rewrite specific branches
git filter-repo --refs refs/heads/feature-1 refs/heads/feature-2

# Rewrite all feature branches
git filter-repo --refs 'refs/heads/feature-*'

# Rewrite range
git filter-repo --refs main~10..main
```

> [!NOTE]
>
> This can cause issues with degenerate merge pruning when negative revisions are specified.

### --dry-run

**--dry-run** `boolean` (default: false)

Preview changes without modifying the repository.

**Effects:**

* Runs `git fast-export` and filters output
* Saves original export to `.git/filter-repo/fast-export.original`
* Saves filtered export to `.git/filter-repo/fast-export.filtered`
* Does NOT modify repository
* Does NOT run `git fast-import`
* Disables commit message hash rewriting (new hashes unknown)
* Disables some empty commit filtering (can't query fast-import)

**Example:**

```bash theme={null}
git filter-repo --path src/ --dry-run

# Review the filtered output
cat .git/filter-repo/fast-export.filtered
```

> [!TIP]
>
> Always test with `--dry-run` first for complex operations.

### --debug

**--debug** `boolean` (default: false)

Show additional debugging information.

**Output includes:**

* Commands being run
* File locations for input/output
* Processing steps
* Extra operational details

**With `--dry-run`:** Shows what WOULD be run

**Without `--dry-run`:** Shows what IS being run

**Example:**

```bash theme={null}
git filter-repo --path src/ --debug
```

## Input Options

### --stdin

**--stdin** `boolean` (default: false)

Read fast-export stream from stdin instead of running git fast-export.

**Requirements:**

* Input must be in expected fast-export format
* Must include `original-oid` directives

**Use cases:**

* Custom pre-processing of export stream
* Combining multiple export streams
* Testing with pre-generated exports

**Example:**

```bash theme={null}
# Generate export separately
git fast-export --show-original-ids --all > export.dat

# Filter it
cat export.dat | git filter-repo --stdin
```

## Sensitive Data Removal

### --sensitive-data-removal, --sdr

**--sensitive-data-removal** `boolean` (default: false)

Enable sensitive data removal mode.

**Aliases:** `--sdr`

**Additional actions:**

* Fetches all refs from origin (unless `--no-fetch`)
* Tracks and reports first changed commits
* Tracks orphaned LFS objects
* Provides detailed cleanup instructions

**Example:**

```bash theme={null}
git filter-repo --replace-text secrets.txt --sensitive-data-removal
```

> [!WARNING]
>
> May discard local-only changes during fetch. Use `--no-fetch` if you have unpushed changes.

### --no-fetch

**--no-fetch** `boolean` (default: false)

Skip the automatic fetch when using `--sensitive-data-removal`.

**Effect:** Prevents overwriting local-only changes

**Risk:** May leave sensitive data in unfetched refs

**Automatically enabled by:** `--partial` or any flag implying `--partial`

**Example:**

```bash theme={null}
git filter-repo --sdr --no-fetch --replace-text secrets.txt
```

## Output Control

### --quiet

**--quiet** `boolean` (default: false)

Suppress progress output and pass `--quiet` to git commands.

**Example:**

```bash theme={null}
git filter-repo --path src/ --quiet
```

### --no-gc

**--no-gc** `boolean` (default: false)

Skip running `git gc` after filtering.

**Default behavior:** Runs `git gc --aggressive` after filtering

**Use `--no-gc` when:**

* You'll run multiple filter-repo commands
* You want to run gc manually later
* You're doing partial filtering

**Example:**

```bash theme={null}
git filter-repo --path src/ --no-gc
```

## Ordering Options

### --date-order

**--date-order** `boolean` (default: false)

Process commits in commit timestamp order.

**Default:** Topological order (parents before children)

**Effect:** Processes commits by author/commit date instead

**Example:**

```bash theme={null}
git filter-repo --date-order
```

## Utility Options

### --help, -h

**--help** `boolean`

Show help message and exit.

**Aliases:** `-h`

**Example:**

```bash theme={null}
git filter-repo --help
```

### --version

**--version** `boolean`

Display git-filter-repo version and exit.

**Example:**

```bash theme={null}
git filter-repo --version
```

### --analyze

**--analyze** `boolean` (default: false)

Analyze repository without modifying it.

**Output:** Creates reports in `.git/filter-repo/analysis/`

**Reports include:**

* Blob sizes by path/extension
* Path renames over time
* Large objects
* Directory statistics

**Example:**

```bash theme={null}
git filter-repo --analyze
ls .git/filter-repo/analysis/
```

[Learn more about analysis →](https://newren-git-filter-repo.mintlify.site/use-cases/analyzing-repository.md)

### --proceed

**--proceed** `boolean` (default: false)

Avoid triggering the no-arguments-specified check.

Use this when you want to run git-filter-repo with only callback options and no filtering flags. Without this flag, git-filter-repo will complain if you don't specify any filtering options.

**Example:**

```bash theme={null}
# Run with only a callback, no filtering
git filter-repo --commit-callback 'print(commit.message)' --proceed
```

## Usage Examples

### Filter Between Repositories

```bash theme={null}
# Filter from source to new clean repository
git filter-repo \
  --source ./messy-repo \
  --target ./clean-repo \
  --path important-code/
```

### Dry Run Before Real Filtering

```bash theme={null}
# Test first
git filter-repo --path src/ --dry-run

# Review output
less .git/filter-repo/fast-export.filtered

# If looks good, run for real
git filter-repo --path src/
```

### Multiple Sequential Filters

```bash theme={null}
# Run multiple filters, skip gc until done
git filter-repo --path src/ --no-gc
git filter-repo --replace-text secrets.txt --no-gc
git filter-repo --strip-blobs-bigger-than 10M --no-gc

# Now run gc once at end
git gc --aggressive
```

### Sensitive Data Removal

```bash theme={null}
# Remove sensitive data with full cleanup
git filter-repo \
  --replace-text secrets.txt \
  --sensitive-data-removal

# Check generated reports
cat .git/filter-repo/first-changed-commits
cat .git/filter-repo/orphaned_lfs_objects
```

### Partial History Rewrite

```bash theme={null}
# Rewrite only specific branches
git filter-repo \
  --refs refs/heads/feature-1 refs/heads/feature-2 \
  --path src/
```

## Important Notes

> [!WARNING]
>
> **Fresh Clone Requirement**
>
> git-filter-repo expects to run on a fresh clone. Use `--force` to override this check, but ONLY if you have backups.

> [!NOTE]
>
> **Mixing Old and New History**
>
> `--partial` mode mixes old and new history. This is usually not what you want for a clean history rewrite.

> [!TIP]
>
> **Always Test First**
>
> Use `--dry-run` and `--debug` for complex operations:
>
> ```bash theme={null}
> git filter-repo --path src/ --dry-run --debug
> ```

## See Also

* [CLI Overview →](https://newren-git-filter-repo.mintlify.site/api/cli-overview.md) - All command options
* [Path Options →](https://newren-git-filter-repo.mintlify.site/api/path-options.md) - Filter by path
* [Content Options →](https://newren-git-filter-repo.mintlify.site/api/content-options.md) - Modify content
* [Examples →](https://newren-git-filter-repo.mintlify.site/examples/cheat-sheet.md) - Real-world usage


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.