LinuxCommandLibrary

git-gc

Optimize Git repository by garbage collecting

TLDR

Optimise the repository

$ git gc
copy

Aggressively optimise, takes more time
$ git gc --aggressive
copy

Do not prune loose objects (prunes by default)
$ git gc --no-prune
copy

Suppress all output
$ git gc --quiet
copy

Display help
$ git gc --help
copy

SYNOPSIS

git gc [--aggressive] [--auto] [--prune=|now] [--quiet] [--force]

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=|now
    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)

Copied to clipboard