DOCSEARCHbyAlgolia
Submit Docs

git-sizer

repository·master·Indexed 26 days ago

https://github.com/github/git-sizer

A tool that computes size metrics for local Git repositories to identify performance bottlenecks and unconventional structures. It analyzes overall repository size, reference and object counts, gigantic blobs, large text file deltas, and bizarre structures that may impact cloning, repacking, or general Git operations. Supports tabular and JSON output, configurable reporting thresholds, and reference filtering via inclusion and exclusion patterns.

Tokens
2.1K
Snippets
5
Records
16
Agent score
86%

What's inside git-sizer

  1. Overview of git-sizer metrics

    master

    git-sizer computes various size metrics to identify potential performance bottlenecks in a Git repository. It flags issues such as:

    • Overall Repository Size: Checks if the repo is unwieldy (ideally < 1 GiB, problematic > 5 GiB).
    • Reference Count: Monitors the number of branches and tags (aim for a few tens of thousands at most).
    • Object Count: Identifies if too many objects are slowing down history traversal and garbage collection.
    • Gigantic Blobs: Flags excessively large individual files.
    • Large Text File Deltas: Detects frequent changes to large text files (e.g., logs, XML) that make reconstruction expensive.
    • Gigantic Trees: Identifies directories with too many entries, which makes tree creation and traversal expensive.
    • File Repetition: Detects if the same or similar files are repeated at different paths within a single commit (potential "git bombs").
    • Path Lengths: Flags absurdly long path names.
    • Bizarre Structures: Detects annotated tag chains, massive octopus merges, or gigantic commit log messages.

  2. Build git-sizer from source using make

    master

    For developers or users on Linux/OS X who want to build from the repository, you can use make. This requires Go to be installed. You can optionally enable isatty() support (which affects how --progress behaves in non-TTY outputs) if you have a C toolchain available.

    git clone https://github.com/github/git-sizer.git
cd git-sizer
./script/bootstrap
make
# Or with isatty support:
make USE_ISATTY=true

  3. Install git-sizer using go install

    master

    To install the latest version of git-sizer using the Go toolchain, ensure you have a recent version of Go installed and your GOPATH is set. Use go install to download and compile the binary, which will be placed in $GOPATH/bin/.

    go install github.com/github/git-sizer@latest

  4. Inspect large objects identified by git-sizer

    master

    The git-sizer output includes footnotes containing the SHA-1s of the largest objects found. To view the contents of a specific large object, use the git cat-file -p command with the <commit>:<path> description provided in the footnote.

    Example:

    git cat-file -p 91cc53b0c78596a73fa708cceb7313e7168bb146:drivers/gpu/drm/amd/include/asic_reg/vega10/NBIO/nbio_6_1_sh_mask.h

  5. Install git-sizer

    master

    To use git-sizer, you must first ensure that the Git command-line client is installed and is version >= 2.6. The git command must be available in your PATH because git-sizer invokes Git commands to analyze your repository.

    Option 1: Install a released version (Recommended)

    1. Download the ZIP file for your platform from the releases page.
    2. Unzip the file.
    3. Move the executable (git-sizer or git-sizer.exe) into a directory in your PATH.

    Option 2: Build from source

    Follow the instructions provided in docs/BUILDING.md to build the binary manually.

  6. Run git-sizer to analyze a repository

    master

    To analyze a Git repository, navigate to the directory containing a full, non-shallow clone of the repository and execute the tool.

    Basic Usage

    You can run the tool without any options to get a default analysis:

    git-sizer

    Running via Git (Pro tip)

    If you add git-sizer to your PATH, you can invoke it using the git sizer syntax. This allows you to use standard Git flags, such as specifying a different repository directory with -C:

    git -C /path/to/my/repo sizer

    If git-sizer is not in your PATH, you must provide the full path to the executable:

    /path/to/bin/git-sizer
    git-sizer

  7. Analyze a Git repository with git-sizer

    master

    Run git-sizer within a Git repository to output a tabular report of its size, object counts, and potential performance bottlenecks. By default, it only reports statistics that meet a minimal level of concern. Use the --verbose flag to see all statistics, including those with low concern levels.

    git-sizer --verbose

  8. Use git-sizer CLI to scan Git repositories

    master
    git-sizer scans objects in a Git repository and emits statistics about them. By default, it processes all objects reachable from any reference. You can specify explicit roots (like main or a specific SHA-1) to limit the traversal to only those objects and their descendants.

  9. Configure git-sizer output verbosity and thresholds

    master

    Control which statistics are reported based on their 'Level of concern' (indicated by asterisks in the table output):

    • --verbose: Output all statistics, regardless of concern level.
    • --threshold=<value>: Suppress statistics below a specific concern level. <value> is a numerical value corresponding to the number of asterisks.
    • --critical: Report only statistics with a critical level of concern (equivalent to --threshold=30).

  10. Export git-sizer results in JSON format

    master

    To obtain machine-readable output containing exact numbers instead of human-readable approximations (like 'k', 'M', 'G'), use the --json flag. You can specify the schema version using --json-version:

    • --json: Enable JSON output.
    • --json-version=1: Use the old style JSON output.
    • --json-version=2: Use the new style JSON output.

  12. Reference: git-sizer CLI flags

    master

    The following flags are available for the git-sizer command line interface:

    FlagShortDescription
    --thresholdMinimum level of concern to report. Default: 1.
    --verbose-vReport all statistics. Equivalent to --threshold=0.
    --no-verboseReport only concerning statistics. Equivalent to --threshold=1.
    --criticalOnly report critical statistics. Equivalent to --threshold=30.
    --namesDisplay names of large objects (none, hash, full). Default: full.
    --json-jOutput results in JSON format.
    --json-versionChoose JSON format version (1 or 2). Default: 1.
    --progressReport progress to stderr.
    --no-progressSuppress progress output.
    --versionReport the git-sizer version number.
    --show-refsList the references being processed.
    --branchesProcess branches.
    --tagsProcess tags.
    --remotesProcess remote-tracking references.
    --notesProcess git-notes references.
    --stashProcess refs/stash.
    --includeInclude references by PREFIX or /REGEXP/ or @REFGROUP.
    --excludeExclude references by PREFIX or /REGEXP/ or @REFGROUP.