git-gc
Optimize Git repository by garbage collecting
TLDR
Optimise the repository
Aggressively optimise, takes more time
Do not prune loose objects (prunes by default)
Suppress all output
Display help
SYNOPSIS
git gc [--aggressive] [--auto] [--prune=
PARAMETERS
--aggressive
Perform more thorough (but slower) optimization. It typically spends more time compacting the repository, but may improve disk space utilization and performance.
--auto
Run git gc only if it is deemed necessary based on internal heuristics. This is the default behavior when git gc is run without any options.
--prune=
Prune loose objects older than the specified date. If date is "now", prune loose objects regardless of their age. Defaults to 2 weeks ago.
--quiet
Suppress all progress reports.
--force
Force git gc to run even if the repository is already in a relatively good state. May be needed to recover from corruption or errors.
DESCRIPTION
The git gc (garbage collect) command is used to clean up a Git repository by removing unnecessary files and optimizing the repository database.
It performs several maintenance tasks, including:
1. Consolidating loose objects into packfiles to reduce disk space and improve performance.
2. Pruning unreachable objects (commits, trees, blobs) that are no longer referenced.
3. Compressing file revisions (if `--aggressive` option used).
This command helps maintain a healthy and efficient Git repository by preventing it from becoming bloated with unnecessary data, especially after a large number of commits, branches, or operations that create temporary objects. Regularly running git gc improves the speed and responsiveness of Git operations.
CAVEATS
Running git gc aggressively can take a significant amount of time, especially on large repositories. Avoid running it during peak usage times. Running `git gc --aggressive` can potentially rewrite history, which could cause issues if other users are working with the repository and haven't fetched/pulled the rewritten history. Be cautious with this option.
AUTOMATIC GARBAGE COLLECTION
Git automatically runs git gc under certain conditions, such as when a large number of loose objects accumulate. This behavior is controlled by configuration variables like `gc.auto` and `gc.pruneExpire`.
You can adjust these variables to fine-tune the automatic garbage collection process to suit your specific needs. For example, increasing the value of `gc.auto` will delay automatic garbage collection until more objects accumulate.
CONFIGURATION
Several configuration options affect the behavior of `git gc`. Key options include:
`gc.auto`: Controls the threshold for automatic garbage collection.
`gc.pruneExpire`: Determines the age of loose objects to be pruned during garbage collection.
`gc.aggressiveDepth`: Configures the depth used when running with the `--aggressive` option.
`gc.packRefs`: Determines whether references should be packed into the packed-refs file.
HISTORY
git gc has been part of Git since its early days, evolving alongside the Git repository format and optimization techniques. Its purpose has always been to maintain the health and efficiency of Git repositories by removing unnecessary objects and consolidating data.
Over time, the command has been refined with new options and algorithms to improve its performance and effectiveness in different scenarios. The `--aggressive` option, for instance, was added to allow for more thorough optimization, while the `--auto` option automates the garbage collection process based on predefined heuristics.
SEE ALSO
git prune(1), git repack(1), git reflog(1)