# git-identity

## Purpose

Switch the git author identity (user.name + user.email) for the current repo or globally, from a menu of identities saved in `~/.git-identities`.

## Usage

```
git-identity [OPTIONS] [ALIAS]
```

### Arguments

| Argument | Default | Description |
|----------|---------|-------------|
| `ALIAS` | — | Apply this saved identity directly (non-interactive). Omit for the interactive menu. |

### Flags

| Flag | Description |
|------|-------------|
| `--help`, `-h` | Show usage information |
| `--dryrun`, `-n` | Preview all actions without changing config or the identities file |
| `--global`, `-g` | Apply to global git config instead of the current repo |
| `--list`, `-l` | List saved identities and exit |
| `--current`, `-c` | Show the identity in effect for the current directory and exit |

### Environment

| Variable | Description |
|----------|-------------|
| `GIT_IDENTITIES_FILE` | Override the identities file path (default `~/.git-identities`). Used by tests. |

## Identities file format

One identity per line: `alias|Name|email`. Blank lines and lines starting with `#` are ignored.

```
# alias|Name|email
personal|Paul Example|paul@example.net
work|Paul Example|paul.example@corp.com
```

## Behaviour

1. Determine scope: `--global` → global config; otherwise local config if inside a git repository, else fall back to global (with a note).
2. **Direct mode** (`ALIAS` given): look up the alias in the identities file; apply `git config user.name` + `user.email` in the chosen scope; print confirmation showing scope, name, and email.
3. **Interactive mode** (no alias): print the identity currently in effect, then a numbered menu of saved identities plus a final option `s) Something else...`.
   - Selecting a number applies that identity (as in direct mode).
   - `s` opens a submenu: `a) Add identity`, `r) Remove identity`, `q) Cancel`.
     - **Add**: prompts for alias, name, email; validates alias is unique and contains no `|`; validates email contains `@`; appends to the file; then offers to apply it now.
     - **Remove**: numbered menu of identities; selected line is deleted from the file. Never touches git config.
   - `q` or empty input cancels with exit 0.
4. Applying an identity never modifies the identities file; add/remove never modify git config (except the post-add "apply now" offer).

## Dryrun Behaviour

Every mutating action prints a `[dryrun]` line instead of acting:

- Apply: `[dryrun] Would set user.name 'NAME' and user.email 'EMAIL' (--local in /path/to/repo)` (or `(--global)`)
- Add: `[dryrun] Would append 'alias|NAME|EMAIL' to FILE`
- Remove: `[dryrun] Would remove identity 'alias' from FILE`

Menus and prompts still function in dryrun so a full flow can be rehearsed.

## Edge Cases

| Case | Handling |
|------|----------|
| Identities file missing (interactive) | Offer to create it seeded with the current global identity, then continue to menu |
| Identities file missing (direct/`--list`) | Error: "No identities file at FILE (run git-identity to create one)", exit 1 |
| Unknown alias in direct mode | Error: "No identity 'ALIAS' in FILE", exit 1; list available aliases |
| Empty identities file | Menu shows only "Something else..." |
| Duplicate alias on add | Error: "Alias 'X' already exists", re-prompt |
| Alias containing `\|` | Error: "Alias must not contain '\|'", re-prompt |
| Not in a git repo, no `--global` | Note "not inside a git repository — applying globally", apply to global |
| Malformed line in file | Skipped silently (comment/blank handling covers this) |

## Examples

```bash
# Interactive menu
$ git-identity
Current identity (local): Paul Example <paul@example.net>

  1) personal    Paul Example <paul@example.net>
  2) work        Paul Example <paul.example@corp.com>
  s) Something else...

Select [1-2/s/q]: 2
Set user.name 'Paul Example' and user.email 'paul.example@corp.com' (--local in /home/paul/dev/myrepo)

# Direct, dryrun
$ git-identity -n work
[dryrun] Would set user.name 'Paul Example' and user.email 'paul.example@corp.com' (--local in /home/paul/dev/myrepo)

# List
$ git-identity --list
personal    Paul Example <paul@example.net>
work        Paul Example <paul.example@corp.com>
```