Installation & Setup

Get .git running on your local machine in under 3 minutes. Follow the steps below for your operating system, verify the installation, and configure your initial workspace.

Prerequisites

Before installing .git, ensure your system meets the following requirements:

OS: macOS 12+, Windows 10/11 (x64), or Linux (Ubuntu 20.04+, Debian 11+, Alpine, RHEL 8+)
Runtime: Node.js 18+ or Deno 1.38+ (for extended JS/TS integrations)
Git: v2.35+ (bundled in most installers)
Disk Space: ~450MB for core binaries + cache

💡 Pro Tip If you're using NixOS or Windows WSL2, refer to the platform-specific notes at the end of this guide for optimized configurations.

Installation

Select your preferred package manager or operating system below to begin:

Bash / Zsh

# Using Homebrew
brew install .git/cli

# Verify installation
.git --version

Homebrew handles all dependencies automatically. The CLI will be linked to /opt/homebrew/bin/.git (Apple Silicon) or /usr/local/bin/.git (Intel).

PowerShell

# Using winget (recommended)
winget install .git.cli

# Alternative: Scoop
scoop install .git

# Verify
.git --version

Administrative privileges may be required. After installation, restart your terminal or IDE to update PATH.

Ubuntu/Debian

# Add official repository
curl -fsSL https://pkg.git.dev/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/git-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/git-archive-keyring.gpg] https://pkg.git.dev stable main" | sudo tee /etc/apt/sources.list.d/git.list

# Install
sudo apt update && sudo apt install .git-cli

For RHEL/CentOS/Alpine, refer to the Linux package matrix for native RPM and APK instructions.

npm / yarn / pnpm

# Global installation
npm install -g .git-cli
# or
yarn global add .git-cli
# or
pnpm add -g .git-cli

# Verify
.git --version

⚠️ Note The npm distribution is primarily designed for project-level tooling and JS/TS integrations. For native CLI performance, use your OS package manager.

Verification

Confirm the installation succeeded by running the diagnostic command:

Terminal

.git doctor

# Expected output:
✓ Binary: v2.4.1 (/usr/local/bin/.git)
✓ Git Integration: 2.40.1
✓ Runtime: Node.js 18.17.0
✓ Config: ~/.config/.git/config.yaml
✓ Network: Connected (latency: 42ms)
✓ Ready for initialization

If any check fails, consult the Troubleshooting section below.

Initial Setup

Once verified, configure your workspace with the interactive setup wizard:

Initialize your identity
Set your default author for commits and telemetry opt-ins.

CLI

.git config init # Prompts for: - Full name & email - Default editor (vim, nvim, vscode, etc.) - Telemetry preferences (anonymous usage stats)
Link to remote provider
Connect your existing GitHub, GitLab, or Bitbucket account for seamless authentication.

CLI

.git auth login --provider github # Opens browser for OAuth. Token stored securely in system keychain.
Clone or create a repository
Test your setup by pulling a starter project or initializing a new one.

CLI

.git init my-project cd my-project .git status # Should show clean working tree

Troubleshooting

Common issues and quick fixes:

This usually means your PATH isn't updated. Run hash -r (Bash/Zsh) or restart your terminal. If using npm, ensure your global bin directory is in PATH.

Ensure your system's CA certificates are up to date. On Linux, run sudo apt install ca-certificates. You can also force TLS 1.2+ with .git config set http.sslVersion TLSv1.2.

.git uses the native OS keychain (macOS Keychain, Windows Credential Manager, libsecret on Linux). Ensure your user has read/write access, or disable secure storage with .git config set auth.secure false (not recommended for production).

💡 Still stuck? Run .git doctor --verbose to generate a diagnostic report, then share it on our GitHub Discussions or join the Discord channel for real-time support.