Git over SSH - Cargo Generate Documentation
Description: cargo, make me a project

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Git over SSH

New in version 0.7.0 is the support for both public and private and ssh git remote urls. New in version 0.22.0 is the support for `ssh-agent` on Windows and interactively asking for passphrase for password protected keys on *Nix and macOS.

There are 2 different git over ssh urls, one with the `git@` prefix and one with the `ssh://` prefix. Both are supported. Please note that the `ssh://` prefix url uses a path where the `git@` prefix uses a colon at the user/github-org level. For example:

    git@github.com:rustwasm/wasm-pack-template.git

    # vs

    ssh://git@github.com/rustwasm/wasm-pack-template.git

Both those urls can also be used in the `.gitconfig` insteadOf configuration, see more in the section below.

    cargo generate --git git@github.com:rustwasm/wasm-pack-template.git --name mywasm

## Authentication using `ssh-agent`

New in version 0.15.1 is the `ssh-agent` usage for password protected keys. It's also the default mechanism on Windows.

### On Windows

`ssh-agent` is the default and also the only possibility to get git+ssh working. Please follow this guide to get `ssh-agent` configured on windows.

### On *Nix and macOS

If you omit the identity file (read the next paragraph) OR a provided identity file does not exist, then the default is to use `ssh-agent`.

## Ssh identity file defaults

Since version 0.22.0 the default mechanism on unix/macOS is to use the function `add_default_ssh_keys` that adds a couple of default keys to look up first.

    // the list used..
    let candidates = [
    			"id_rsa",
    			"id_ecdsa,",
    			"id_ecdsa_sk",
    			"id_ed25519",
    			"id_ed25519_sk",
    			"id_dsa",
    		];

## Custom ssh identity file (private key)

However, if you use a different file, you can pass a custom ssh identity with via `-i | --identity` like `-i ~/.ssh/id_rsa_other` as argument.

If the file is passphrase protected cargo-generate will ask for the passphrase interactively.

If you permanently want to use a custom identity file, you can configure it in the cargo-generate config file like this:

    # an extract of ~/.cargo/cargo-generate.toml
    [defaults]
    # note that `~/` and `$HOME/` are going to be expanded to the full path seamlessly
    ssh_identity = "~/.ssh/id_rsa_other"
    # that is equivalent to
    ssh_identity = "$HOME/.ssh/id_rsa_other"
    # that is equivalent to
    ssh_identity = "/home/john/.ssh/id_rsa_other"

> ⚠️ NOTE: that the cli argument `-i` always overrules the `ssh_identity` from the config file.