How to use the command git filter-repo (with examples)

The git filter-repo command is a versatile tool for rewriting Git history. It can be used to modify the commit history, extract or remove specific files or folders, and rename paths. This command is particularly useful when working with Git repositories that contain sensitive information or when restructuring the repository.

Use case 1: Replace a sensitive string in all files

Code:

git filter-repo --replace-text <(echo 'find==>replacement')

Motivation: The motivation for using this example is to replace a sensitive string that appears in multiple files within the Git repository. For example, this could be used to replace a password or a server URL across all files, ensuring that the sensitive information is not exposed.

Explanation:

• --replace-text: This argument is used to specify the replacement text. In this example, the replacement text is provided as <(echo 'find==>replacement'). The string 'find==>replacement' specifies the string to be found, followed by the replacement string, separated by ==>.
• The <(...) construct in the command is for process substitution, which allows the output of a command to be used as an input. In this case, it is used to pass the replacement text to the --replace-text argument.

Example output: This command will search for the specified string 'find' in all files within the Git repository and replace it with the string 'replacement'. The output will show the progress of the replacement operation and provide a summary of the changes made.

Use case 2: Extract a single folder, keeping history

Code:

git filter-repo --path path/to/folder

Motivation: The motivation for using this example is to extract a specific folder from the Git repository while preserving its commit history. This can be useful when working with large repositories and needing to isolate changes related to a particular component or feature.

Explanation:

• --path: This argument is used to specify the path of the folder to be extracted from the Git repository. In this example, the path of the folder to be extracted is given as path/to/folder.

Example output: Running this command will extract the specified folder path/to/folder from the Git repository. The output will show the progress of the extraction process and provide a summary of the changes made, including the new commits that were created.

Use case 3: Remove a single folder, keeping history

Code:

git filter-repo --path path/to/folder --invert-paths

Motivation: The motivation for using this example is to remove a specific folder from the Git repository while preserving its commit history. This can be useful when deciding to exclude a folder from the repository or when splitting a repository into multiple smaller ones.

Explanation:

• --path: This argument is used to specify the path of the folder to be removed from the Git repository. In this example, the path of the folder to be removed is given as path/to/folder.
• --invert-paths: This argument is used to invert the selection of paths. By including this argument, the command will remove everything except for the specified folder path.

Example output: Executing this command will remove the folder specified by path/to/folder from the Git repository while retaining its commit history. The output will display the progress of the removal process and provide a summary of the changes made.

Use case 4: Move everything from sub-folder one level up

Code:

git filter-repo --path-rename path/to/folder/:

Motivation: The motivation for using this example is to move all files and folders inside a sub-folder to its parent folder. This can be useful when restructuring the repository and eliminating unnecessary folder levels.

Explanation:

• --path-rename: This argument is used to specify the path renaming operation. In this example, the sub-folder path/to/folder/ is renamed to : (empty string), effectively moving all files and folders inside it one level up.

Example output: Running this command will move all files and folders inside the sub-folder path/to/folder/ to its parent folder. The output will indicate the progress of the path renaming operation and provide a summary of the changes made, including the new commit(s) created.