npm package: @john-daniels/gitprofile
Description: Manage multiple Git SSH identities and per-repo authors safely.
Latest version: 0.1.0

# gitprofile

A cross-platform CLI tool that helps developers manage multiple Git SSH identities and per-repository authors safely. No global Git config changes, no silent remote rewrites.

## Why gitprofile?

Working with multiple Git accounts (work, personal, clients) can be confusing. `gitprofile` makes it simple:

- ✅ **Repository-scoped authors only** – Never touches global `git config user.*`
- ✅ **Explicit SSH identities** – Use aliases like `github-work` instead of guessing
- ✅ **Clear instructions** – Always shows you exactly how to clone and push
- ✅ **Safe by default** – No silent changes, everything requires confirmation

## Installation

```bash
npm install -g @john-daniels/gitprofile
```

**Requirements:**
- Node.js 18 or higher
- `git` installed
- `ssh-keygen` available (usually pre-installed on macOS/Linux)

## Quick Start

### 1. Create your first profile

```bash
gitprofile init
```

This will:
- Generate a new SSH key (e.g., `~/.ssh/id_ed25519_work`)
- Ask for your author name and email
- Optionally add an SSH alias to `~/.ssh/config`
- Show you your public key to add to GitHub/GitLab

### 2. Use your profile

After setup, `gitprofile` shows you exactly how to use it:

**Clone a repository:**
```bash
git clone git@github-work:ORG/REPO.git
```

**Update an existing repository:**
```bash
git remote set-url origin git@github-work:ORG/REPO.git
```

**Set author for current repository:**
```bash
gitprofile set author
```

## Commands

### `gitprofile` (no args)
Shows a high-level overview of available commands.

### `gitprofile init`
Create a new Git profile (SSH key + author). Interactive prompts guide you through:
- Profile nickname (e.g., `work`, `personal`)
- Author name and email
- Git provider (GitHub, GitLab, Bitbucket)
- Whether to add SSH alias to `~/.ssh/config`
- Whether to apply author to current repository (if in a Git repo)

### `gitprofile list`
List all configured profiles with their details:
- Nickname
- Author name and email
- SSH alias
- SSH key path
- Provider

### `gitprofile set author`
Apply an existing profile's author to the current Git repository. Only modifies local repository config, never global.

### `gitprofile help`
Show detailed help explaining:
- Core concepts (SSH identity vs Git author)
- How configuration works
- Where files are stored

### `gitprofile doctor`
Run diagnostics to check:
- Git installation
- SSH directory and keys
- ssh-agent status

## How It Works

### SSH Identity vs Git Author

These are two separate concepts that `gitprofile` keeps clear:

- **SSH alias** (e.g., `github-work`) – Controls which account you authenticate as when talking to GitHub/GitLab
- **Git author** (name + email) – Controls who commits are attributed to inside a repository

You can use different combinations:
- Same SSH identity, different authors per repo
- Different SSH identities, same author
- Any combination that makes sense for your workflow

### Configuration Storage

- **Profiles:** `~/.gitprofile/config.json` (per-machine, per-user)
- **SSH keys:** `~/.ssh/id_ed25519_<nickname>` (standard SSH location)
- **SSH aliases:** `~/.ssh/config` (only appended when you create profiles)

**Important:** `gitprofile` never modifies:
- Global Git config (`~/.gitconfig`)
- Existing SSH keys
- Git remotes (you update those yourself)

### First-Time Bootstrap

On first run, `gitprofile` scans your system for existing SSH keys and SSH config entries. If found, it offers to import them as profiles. This is completely optional and safe – no files are modified during bootstrap.

## Examples

### Work and Personal Profiles

```bash
# Create work profile
gitprofile init
# Nickname: work
# Author: Jane Doe <jane@company.com>
# Provider: github

# Create personal profile
gitprofile init
# Nickname: personal
# Author: Jane Doe <jane@gmail.com>
# Provider: github
```

Now you can clone work repos with `git@github-work:...` and personal repos with `git@github-personal:...`.

### Per-Repository Authors

```bash
cd ~/projects/work-repo
gitprofile set author
# Select: work

cd ~/projects/personal-repo
gitprofile set author
# Select: personal
```

Each repository now has its own author config, independent of global settings.

## Platform Support

- ✅ macOS
- ✅ Linux
- ✅ Windows (with Git Bash or WSL)

## Safety Guarantees

- ❌ **No global Git mutations** – Only repository-local config changes
- ❌ **No silent remote rewrites** – You control your remotes manually
- ✅ **Every destructive action requires confirmation**
- ✅ **All output is copy-paste friendly**

## Troubleshooting

### SSH alias not working?

Make sure `~/.ssh/config` has the Host block. Run `gitprofile init` again and say "yes" when asked to add the SSH alias, or add it manually:

```
Host github-<nickname>
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_<nickname>
    IdentitiesOnly yes
```

### Can't clone with alias?

Verify your SSH key is added to your Git provider (GitHub/GitLab). The public key is shown after `gitprofile init`.

### Check everything

Run `gitprofile doctor` to see diagnostics for Git, SSH, and ssh-agent.

## Contributing

Contributions welcome! See [CONTRIBUTORS.md](./CONTRIBUTORS.md) for guidelines.

## License

MIT License – see [LICENSE](./LICENSE) for details.

## Support

Found a bug or have a feature request? Open an issue on GitHub.