# Git + 1Password HTTPS Credential Helper

This setup allows Git to automatically fetch HTTPS credentials from 1Password without storing them locally.

## Prerequisites

1. **1Password CLI installed**: The `op` command should be available

   - On Ubuntu/Debian: Install from 1Password's official repository
   - Package name: `1password-cli` (included in base.txt)

2. **1Password CLI authenticated**: You must be signed in to 1Password CLI

   ```bash
   op signin
   ```

3. **jq installed**: For JSON parsing (included in base.txt)

## Setup

The credential helper is automatically configured in your `.gitconfig`:

```ini
[credential]
helper = !~/.dotfiles/scripts/git-credential-1password.sh
```

## Usage

### Storing Credentials in 1Password

For each Git HTTPS remote you want to use, create an item in 1Password with:

1. **Title**: Include the hostname (e.g., "GitHub", "gitlab.example.com", "bitbucket.org")
2. **Username field**: Your Git username
3. **Password field**: Your Git password/token
4. **URL field** (optional but recommended): The full HTTPS URL of the repository

#### Examples:

**GitHub Personal Access Token:**

- Title: "GitHub"
- Username: your-github-username
- Password: ghp_xxxxxxxxxxxxxxxxxxxx
- URL: https://github.com

**GitLab Token:**

- Title: "gitlab.example.com"
- Username: your-gitlab-username
- Password: glpat-xxxxxxxxxxxxxxxxxxxx
- URL: https://gitlab.example.com

### Using with Git

Once set up, Git operations will automatically prompt 1Password for credentials:

```bash
# Clone a private repo
git clone https://github.com/user/private-repo.git

# Push to origin
git push origin main

# Add a new HTTPS remote
git remote add upstream https://github.com/upstream/repo.git
```

## How It Works

1. When Git needs HTTPS credentials, it calls the credential helper
2. The helper searches 1Password for items matching the hostname
3. It looks for matches in:
   - URL fields containing the hostname
   - Item titles containing the hostname
   - Additional information containing the hostname
4. Returns the username and password to Git
5. Git uses these credentials for the operation

## Troubleshooting

### "1Password CLI (op) not found"

Install 1Password CLI or ensure it's in your PATH:

```bash
# Check if installed
which op

# Install if missing (Ubuntu/Debian)
curl -sS https://downloads.1password.com/linux/keys/1password.asc | sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/amd64 stable main' | sudo tee /etc/apt/sources.list.d/1password.list
sudo apt update && sudo apt install 1password-cli
```

### "Not signed in to 1Password CLI"

Sign in to 1Password CLI:

```bash
op signin
```

### "No matching item found"

- Ensure the 1Password item title or URL contains the Git hostname
- Check that the item has username and password fields
- Try creating a new item with a clear title matching the hostname

### Test the Helper Manually

```bash
# Test the credential helper directly
echo -e "protocol=https\nhost=github.com\n" | ~/.dotfiles/scripts/git-credential-1password.sh get

# Debug: List all 1Password items to see what's available
op item list --format=json | jq -r '.[] | "\(.title) - \(.id)"'

# Debug: See the structure of a specific item
op item get "YOUR_ITEM_ID" --format=json | jq

# Debug: Check what fields are available in an item
op item get "YOUR_ITEM_ID" --format=json | jq -r '.fields[] | "\(.label // .id): \(.value // "empty")"'
```

### Common Issues

**jq null matching errors:**

- This happens when 1Password items have missing fields
- The updated script handles null values gracefully
- Make sure your items have proper username and password fields

**Field naming issues:**

- The script looks for fields with labels containing: "username", "user", "login"
- For passwords, it looks for: "password", "token", "secret", "pass"
- If your fields have different names, rename them in 1Password

## Security Benefits

- Credentials are never stored in plain text on disk
- Works with 1Password's security features (Touch ID, master password, etc.)
- Credentials are fetched fresh each time (no caching)
- Works seamlessly with existing 1Password setup

## Limitations

- Only works with HTTPS Git remotes (SSH remotes continue to use SSH keys)
- Requires 1Password CLI to be signed in
- May prompt for 1Password unlock depending on your security settings