136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
---
|
|
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
|
|
|
|
```gitignore
|
|
# 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:
|
|
|
|
```markdown
|
|
# 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
|