replace
Rewrites every commit that contains a literal string, replacing all occurrences with a new value. Operates on all branches reachable from HEAD by default.
Options
| Flag | Required | Default | Description |
|---|---|---|---|
--from |
Yes | — | Literal string to search for |
--to |
No | REDACTED |
Replacement value |
Examples
sh
# Dry-run — no changes made
gitredact replace --dry-run --from "secret-token" --to "REDACTED"
# Execute with confirmation prompt
gitredact replace --from "secret-token" --to "REDACTED"
# Skip prompt, create a backup ref before rewriting
gitredact replace --from "secret-token" --to "REDACTED" --yes --backup
# Run on a specific repository path
gitredact replace --from "old-host" --to "new-host" --yes /path/to/repo
# Silent — errors only
gitredact replace --from "secret-token" --to "REDACTED" --yes --silentdelete-path
Removes an exact file path from every commit in history. After the rewrite, the file will not appear in any commit, tag, or tree object.
Options
| Flag | Required | Description |
|---|---|---|
--path |
Yes | Repository-relative file path to remove |
Examples
sh
# Dry-run — no changes made
gitredact delete-path --dry-run --path secrets/credentials.txt
# Execute with confirmation prompt
gitredact delete-path --path secrets/credentials.txt --yes
# Include tags in rewrite and create a backup
gitredact delete-path --path secrets/credentials.txt --yes --include-tags --backup
# Silent — errors only
gitredact delete-path --path secrets/credentials.txt --yes --silentGlobal flags
These flags apply to all subcommands.
| Flag | Description |
|---|---|
--dry-run |
Print plan and exit; zero side effects |
--yes |
Skip interactive confirmation |
--include-tags |
Rewrite tags in addition to branches |
--allow-dirty |
Allow running on a dirty worktree |
--verbose |
Verbose output |
--backup |
Create a backup ref (refs/gitredact-backup/<timestamp>) before rewriting; skipped
in dry-run |
--silent |
Suppress all output; only errors are surfaced via exit code |
Exit codes
| Code | Meaning |
|---|---|
0 |
Success |
2 |
Invalid usage |
3 |
Repo validation failure |
4 |
Dirty worktree refusal |
5 |
No matches found in preflight |
6 |
Rewrite execution failure |
7 |
User declined confirmation |
8 |
Verification failure |
9 |
Dependency missing |
Safety notes
⚠ This tool rewrites history permanently and cannot be undone without a backup. Always run with
--dry-run first.
- History is rewritten locally only. The tool does not push anything.
- After a successful run, collaborators must re-clone or hard-reset their copies.
- If the replaced string was a secret, rotate it — rewriting history does not invalidate credentials already in use.
- Use
--backupto save a recovery ref (refs/gitredact-backup/<timestamp>) before rewriting.
💡 Tip: combine
--backup with --dry-run on the first run to understand the scope of
changes before committing.