Git Clients

git-filter-repo – quickly rewrite git repository history

git filter-repo is a versatile tool for rewriting history.

git-filter-repo destructively rewrites history (unless --analyze or --dry-run are given) according to specified rules.

It refuses to do any rewriting unless either run from a clean fresh clone, or --force was given.

While most users will probably just use filter-repo as a simple command line tool (and likely only use a few of its flags), at its core filter-repo contains a library for creating history rewriting tools.

This is free and open source software.

Features include:

  • Several different types of history rewrites are possible; examples include (but are not limited to):
    • Stripping large files (or large directories or large extensions).
    • Stripping unwanted files by path.
    • Extracting wanted paths and their history (stripping everything else).
    • Restructuring the file layout (such as moving all files into a subdirectory in preparation for merging with another repo, making a subdirectory become the new toplevel directory, or merging two directories with independent filenames into one directory).
    • Renaming tags (also often in preparation for merging with another repo).
    • Replacing or removing sensitive text such as passwords.
    • Making mailmap rewriting of user names or emails permanent.
    • Making grafts or replacement refs permanent.
    • Rewriting commit messages.
  • Additionally, several concerns are handled automatically (many of these can be overridden, but they are all on by default):
    • Rewriting (possibly abbreviated) hashes in commit messages to refer to the new post-rewrite commit hashes.
    • Pruning commits which become empty due to the above filters (also handles edge cases like pruning of merge commits which become degenerate and empty).
    • Creating replace-refs for old commit hashes, which if manually pushed and fetched will allow users to continue to refer to new commits using (unabbreviated) old commit IDs.
    • Stripping of original history to avoid mixing old and new history.
    • Repacking the repository post-rewrite to shrink the repo for the user.
  • Safety mechanism:
    • Abort if run from a repo that is not a fresh clone (to prevent accidental data loss from rewriting local history that doesn’t exist anywhere else).
  • Option to analyze a repository and generate reports that can be useful in determining what to filter (or in determining whether a separate filtering command was successful).

Developer: Elijah Newren
License: MIT License

git-filter-repo options

git-filter-repo is written in Python. Learn Python with our recommended free books and free tutorials.

Return to Git Tools

Popular series
Free and Open Source SoftwareThe largest compilation of the best free and open source software in the universe. Each article is supplied with a legendary ratings chart helping you to make informed decisions.
ReviewsHundreds of in-depth reviews offering our unbiased and expert opinion on software. We offer helpful and impartial information.
Alternatives to Proprietary SoftwareReplace proprietary software with open source alternatives: Google, Microsoft, Apple, Adobe, IBM, Autodesk, Oracle, Atlassian, Corel, Cisco, Intuit, and SAS.
GamesAwesome Free Linux Games Tools showcases a series of tools that making gaming on Linux a more pleasurable experience. This is a new series.
Artificial intelligence iconMachine Learning explores practical applications of machine learning and deep learning from a Linux perspective. We've written reviews of more than 40 self-hosted apps. All are free and open source.
Guide to LinuxNew to Linux? Read our Linux for Starters series. We start right at the basics and teach you everything you need to know to get started with Linux.
Alternatives to popular CLI tools showcases essential tools that are modern replacements for core Linux utilities.
System ToolsEssential Linux system tools focuses on small, indispensable utilities, useful for system administrators as well as regular users.
ProductivityLinux utilities to maximise your productivity. Small, indispensable tools, useful for anyone running a Linux machine.
AudioSurveys popular streaming services from a Linux perspective: Amazon Music Unlimited, Myuzi, Spotify, Deezer, Tidal.
Saving Money with LinuxSaving Money with Linux looks at how you can reduce your energy bills running Linux.
Home ComputersHome computers became commonplace in the 1980s. Emulate home computers including the Commodore 64, Amiga, Atari ST, ZX81, Amstrad CPC, and ZX Spectrum.
Now and ThenNow and Then examines how promising open source software fared over the years. It can be a bumpy ride.
Linux at HomeLinux at Home looks at a range of home activities where Linux can play its part, making the most of our time at home, keeping active and engaged.
Linux CandyLinux Candy reveals the lighter side of Linux. Have some fun and escape from the daily drudgery.
DockerGetting Started with Docker helps you master Docker, a set of platform as a service products that delivers software in packages called containers.
Android AppsBest Free Android Apps. We showcase free Android apps that are definitely worth downloading. There's a strict eligibility criteria for inclusion in this series.
Programming BooksThese best free books accelerate your learning of every programming language. Learn a new language today!
Programming TutorialsThese free tutorials offer the perfect tonic to our free programming books series.
Linux Around The WorldLinux Around The World showcases usergroups that are relevant to Linux enthusiasts. Great ways to meet up with fellow enthusiasts.
Stars and StripesStars and Stripes is an occasional series looking at the impact of Linux in the USA.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments