Introduction
The git prune command deletes all the files in a Git repository that are unreachable from the current branch. prune helps clean up the repository when it gets cluttered with files you no longer need or when you finish working on a project. Therefore, this command reduces the repository size.
In this tutorial, you will learn how to use the git prune command.
Prerequisites
- Git installed (follow our tutorials to install Git on Ubuntu, macOS, Windows, CentOS 7, or CentOS 8).
- A Git repository.
git prune Syntax
The git prune command runs the git fsck --unreachable command using all the references available in refs/ and then removes the unreachable ones. The git fsck command is often used to diagnose potential issues and to see which objects may be candidates for removal using git prune.
Note: The git gc command is an alternative for git prune, as it identifies and removes unreferenced or "dangling" objects that are no longer reachable from any branch, tag, or reference. The git gc command stands for garbage collection, and it optimizes and cleans up the repository.
The git prune command has the following syntax:
git prune [options]The available options control the command's behavior, and they are discussed in the section below.
git prune Options
The options are not mandatory. Running git prune without specifying any options causes it to perform its basic function, that is, to remove unreferenced objects from a Git repository.
The options allow you to customize the command's behavior to suit your needs or to provide additional information and control over the pruning process. The following table shows a list of options that git prune accepts:
| Short option | Long option | Description |
|---|---|---|
-n | --dry-run | Performs a dry run of the pruning operation to display which objects will be pruned without removing them. The option is useful for previewing the effects of the prune operation. |
-v | --verbose | Provides a more detailed output about the objects being pruned, including object IDs. |
-f | --force | Forces the pruning operation even if risky. This option can override safety checks that might prevent certain objects from being pruned. |
--progress | Displays a progress indicator during the pruning process, showing the progress as objects are removed. This option is useful for large repositories, allowing you to track the operation's status. | |
--expire=[time] | Sets a time-based expiration for pruning. Objects older than the specified [time] are removed. This option helps you clean up old objects from your repository. | |
-- | Instructs Git to treat everything that follows as arguments, even if they might look like options. This option is helpful in cases where an argument could be mistaken for an option. | |
[head] | Instructs Git to keep objects reachable from the listed [head]s, in addition to objects reachable from any of your references. |
How to Use git prune Command
This section provides practical, hands-on examples for using the git prune command.
Basic git prune Usage
The basic git prune usage is to remove objects in your Git repository that are no longer reachable from any of the references (e.g., branches, tags). Unreachable objects accumulate over time as you make commits, create branches, and then delete some branches.
Running the following command removes all those unreferenced objects:
git pruneThe command cleans up any unreferenced objects, freeing up disk space and cleaning up your repository. There is no output, but if you want to see which objects are pruned, add the --verbose option:
Git deletes all unreachable objects and outputs a list of removed objects.
Perform Dry Run
The dry run feature lets you see which objects the pruning action removes without removing them. Run the git prune command with the --dry-run option to output a list of unreachable objects that the action would prune:
git prune --dry-run
The command outputs a list of unreachable objects without deleting them. The list includes the object ID and its type.
Force Prune Unreachable Objects
To make sure all unreachable objects are removed from the repository without asking for confirmation, specify the --force option:
git prune --forceBe cautious when using the --force option, as pruning objects permanently removes them from the repository.
Prune Remote Branches
If you collaborate on a project with a remote repository, your repository may accumulate unnecessary remote tracking branches over time. To remove unreachable objects associated with those remote branches, use the git remote prune command with the remote repository name.
For example:
git remote prune originThe command removes all references to branches on the origin remote that no longer exist on the remote repository. It also prunes unreachable objects associated with those branches.
Note: See how to remove a Git remote from a repository or reset to a remote branch.
Pruning with an Expiration Date
The --expire [time] option allows users to specify the minimum age of loose objects that will be deleted. Git stores loose objects in separate files rather than in a packed file. They are created when you first clone a repository or when you run git checkout or git switch to switch to a different branch.
Use the --expire option to specify a time or date from which objects are eligible for pruning. You can specify [time] in different ways:
- A relative time, such as
1.weekor6.months. Git deletes loose objects older than the specified time relative to the current time. - An absolute time, such as
2023-11-03 13:25:37 PST. Git deletes loose objects older than the specified time. - A special value, such as
nowornever. The valuenowmakes Git delete all loose objects immediately, regardless of their age. The valueneverinstructs Git not to delete any loose objects, even if they are old.
For example, to remove objects that are older than 14 months and see the operation results, run the following command:
git prune --expire=14.months --verbose
This command prunes objects that haven't been reachable for at least 14 months and outputs the list of pruned objects.
Conclusion
This tutorial showed how to use the git prune command to delete all unreachable objects from your repository, allowing you to clean up the repository. Git prune helps remove clutter after you finish working on a project and saves disk space.
For more Git tutorials, learn about different branching strategies or see how to delete a Git branch remotely and locally.
