---
name: git-setup
description: Configure git user identity, SSH signing, GPG commit signing, global gitconfig, and common git aliases
license: MIT
compatibility: opencode
metadata:
  platform: macos,linux
  category: devops
---

## What I do

Guide the initial configuration of git on a new machine — from basic identity settings to GPG commit signing and productivity aliases.

## When to use me

Use this skill when the user wants to:
- Set up git user name and email for the first time
- Configure GPG signing for verified commits
- Set up useful git aliases and defaults
- Troubleshoot git configuration issues
- Migrate git config to a new machine
- Configure git for multiple identities (work vs personal)

## Workflow

### Step 1: Check current git configuration

```bash
git config --global --list
```

If empty, git has not been configured yet.

### Step 2: Set user identity

Ask the user for their name and email:

```bash
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
```

Verify:
```bash
git config --global user.name
git config --global user.email
```

### Step 3: Set default branch name

```bash
git config --global init.defaultBranch main
```

### Step 4: Configure useful default settings

```bash
# Better error messages with color
git config --global color.ui auto

# Line ending handling (macOS/Linux)
git config --global core.autocrlf input

# Prune deleted remote branches on fetch
git config --global fetch.prune true

# Push only current branch by default
git config --global push.default current

# Rebase when pulling (cleaner history)
git config --global pull.rebase true

# Faster diff algorithm
git config --global diff.algorithm histogram

# Auto-stash before rebase
git config --global rebase.autoStash true
```

### Step 5: Set up useful git aliases

```bash
# Compact status
git config --global alias.st status

# Pretty log
git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

# Compact diff
git config --global alias.d diff

# Show all branches sorted by last commit
git config --global alias.branches "for-each-ref --sort=-committerdate refs/heads/ --format='%(HEAD) %(color:yellow)%(refname:short)%(color:reset) - %(color:red)%(objectname:short)%(color:reset) - %(contents:subject) - %(authorname) (%(color:green)%(committerdate:relative)%(color:reset))'"

# Amend last commit
git config --global alias.amend "commit --amend --no-edit"

# Undo last commit (keep changes)
git config --global alias.undo "reset --soft HEAD~1"

# Show all aliases
git config --global alias.aliases "config --get-regexp '^alias\.'"
```

### Step 6: Configure GPG commit signing (optional)

**Check if GPG is available:**
```bash
gpg --version
```

**If not installed:**
```bash
brew install gnupg    # macOS
# sudo apt install gnupg  # Linux (Debian/Ubuntu)
```

**Generate a GPG key:**
```bash
gpg --full-generate-key
# Select: (1) RSA and RSA, 4096 bits, no expiration
# Enter name and email (must match your git email)
```

**Get the key ID:**
```bash
gpg --list-secret-keys --keyid-format LONG
# Output: sec   rsa4096/ABCDEF1234567890 2024-01-01 [SC]
# Key ID is: ABCDEF1234567890
```

**Configure git to use the key:**
```bash
git config --global user.signingkey ABCDEF1234567890
git config --global commit.gpgsign true
```

**Get the public key for GitHub/GitLab:**
```bash
gpg --armor --export ABCDEF1234567890 | pbcopy   # macOS
# gpg --armor --export ABCDEF1234567890           # Linux (display to copy)
```

Guide user to add the public key:
- GitHub: https://github.com/settings/gpg/new
- GitLab: https://gitlab.com/-/profile/gpg_keys

### Step 7: Work vs personal identity (per-directory config)

For users with both work and personal Git accounts:

```bash
# In work projects directory
git config --global includeIf.gitdir:~/work/.path ~/.gitconfig-work

# Create ~/.gitconfig-work
cat > ~/.gitconfig-work << 'EOF'
[user]
  name = Work Name
  email = work@company.com
  signingkey = WORK_GPG_KEY_ID
EOF

# In personal projects directory
git config --global includeIf.gitdir:~/personal/.path ~/.gitconfig-personal

# Create ~/.gitconfig-personal
cat > ~/.gitconfig-personal << 'EOF'
[user]
  name = Personal Name
  email = personal@email.com
  signingkey = PERSONAL_GPG_KEY_ID
EOF
```

### Step 8: Verify final configuration

```bash
git config --global --list
```

## Common gitconfig reference

```bash
# View all settings and their origin
git config --list --show-origin

# Remove a setting
git config --global --unset <key>

# Edit config in editor
git config --global --edit
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Wrong identity on commits | Check `git config user.name` and `git config user.email` in that repo |
| GPG signing fails | Ensure GPG key email matches git config email exactly |
| `gpg: signing failed: Inappropriate ioctl for device` | Add `export GPG_TTY=$(tty)` to ~/.zshrc or ~/.bashrc |
| Mac GPG passphrase popup not appearing | Install `pinentry-mac`: `brew install pinentry-mac` |
| Commits show "Unverified" on GitHub | GPG public key not uploaded to GitHub, or email mismatch |
| SSH git clone still asks for HTTPS password | Run `git config --global url."git@github.com:".insteadOf "https://github.com/"` |

## Key notes for the agent

- **Ask before setting identity** — never guess the user's name/email.
- **Don't overwrite existing config** — show current values first, let user confirm changes.
- **Backup is critical**: `cp ~/.gitconfig ~/.gitconfig.bak.$(date +%s)` before major changes.
- **GPG signing is optional** — don't push it unless the user asks or it's relevant (e.g., open source projects).
- **Work/personal split** — if user mentions multiple GitHub accounts, suggest `includeIf` approach.
- `.gitconfig` is global (~/.gitconfig), not per-project. Per-project settings go in `.git/config`.
- Windows/WSL users follow Linux instructions — no special handling needed for WSL.