version-controlling-global-configuration

name	Version Controlling Global Configuration
description	Use when user asks about version controlling ~/.claude directory or syncing Claude Code settings across machines. Provides git setup instructions and .gitignore patterns to track only portable settings while excluding logs, session data, and machine-specific plugin metadata. Invoke before initializing git in ~/.claude to prevent committing non-portable data.

Version Controlling Claude Code Global Configuration

Use this skill when users want to version control their ~/.claude directory to sync settings across machines.

Critical Understanding

The ~/.claude directory contains both portable settings and machine-specific data. Not everything should be version controlled.

Safe to Version Control

• CLAUDE.md - Global instructions
• settings.json - User preferences (only contains enabled plugin names)
• Documentation files you create (README, PLUGINS.md)

NEVER Version Control

• plugins/installed_plugins.json - Contains absolute paths and timestamps
• plugins/known_marketplaces.json - Contains absolute paths and timestamps
• plugins/config.json - Machine-specific configuration
• plugins/marketplaces/ and plugins/repos/ - Downloaded plugin data
• debug/, file-history/, history.jsonl - Logs and session data (may contain sensitive info)
• projects/, session-env/, shell-snapshots/, todos/ - Session-specific cache
• statsig/ - Analytics cache

Why Plugin Metadata Shouldn't Be Versioned

The plugin metadata files contain:

1. Absolute paths specific to each machine (e.g., /Users/username/...)
2. Timestamps that cause unnecessary merge conflicts
3. Git commit SHAs from local repositories

These files are automatically regenerated by Claude Code when plugins are installed. You don't need to preserve them.

Standard .gitignore Template

# Session data and logs
debug/
file-history/
history.jsonl
session-env/
shell-snapshots/
todos/

# Project-specific cache
projects/

# Analytics and telemetry
statsig/

# Plugin metadata (machine-specific paths and timestamps)
plugins/installed_plugins.json
plugins/known_marketplaces.json
plugins/config.json
plugins/marketplaces/
plugins/repos/

# Any log files
*.log

# Temporary files
*.tmp
*.swp
*~

# OS-specific files
.DS_Store
Thumbs.db

Recommended Workflow

Initial Setup

1. Examine the ~/.claude directory to understand what's there
2. Create .gitignore with the template above
3. Create PLUGINS.md to document which plugins to install:

# Installed Plugins

## Marketplaces
- **marketplace-name**: `https://github.com/user/repo`

## Plugins
From `marketplace-name`:
- `plugin-name` - Brief description

## Installation on New Machine
1. Clone/install marketplaces listed above
2. Use Claude Code to install plugins
3. Copy `settings.json` and `CLAUDE.md` from this repo

4. Create README.md explaining what the repo contains and setup process
5. Initialize git: git init
6. Verify with git status - should only show safe files
7. Commit the initial setup

Cross-Machine Sync

On a new machine:

1. Clone the config repo to ~/.claude
2. Manually install marketplaces and plugins per PLUGINS.md
3. Claude Code will regenerate all machine-specific metadata automatically

Validation Steps

After creating .gitignore:

1. Run git status to see what will be tracked
2. Verify NO plugin metadata files appear
3. Verify NO log or session files appear
4. Should only see: .gitignore, CLAUDE.md, settings.json, and any docs you created

If plugin metadata appears in git status, the .gitignore is incorrect.

Common Mistakes to Avoid

• Don't version control the entire plugins/ directory
• Don't try to preserve absolute paths across machines
• Don't commit history.jsonl (contains conversation history, potentially sensitive)
• Don't assume plugin metadata needs to be preserved

When to Use This Skill

Trigger this skill when users:

• Ask about version controlling ~/.claude
• Want to sync Claude settings across machines
• Ask what's safe to commit from their Claude directory
• Question whether plugin files should be in git