Docs

Set up profiles, connect existing repos (app or terminal), SSH aliases, hooks, and troubleshooting.

← Back to home

What changed on your machine

After setup, GitGuise configures your system so you can work from the terminal without thinking about accounts.

  • SSH keys are generated per profile in ~/.ssh/
  • SSH config adds one Host alias per profile in ~/.ssh/config
  • Hooks / wrappers (if enabled) are installed so git commands can auto-select the right identity
You can keep using your normal terminal. GitGuise just makes the SSH identity + git config consistent.

Add a profile

When you save a profile, GitGuise does the system setup automatically:

  • Generates an SSH key (if missing) at ~/.ssh/id_ed25519_<label>
  • Writes an SSH Host alias into ~/.ssh/config (for example github-work)
  • Copies the public key and shows a guided “Add SSH key” step (GitHub / GitLab / Bitbucket)

The only manual step is adding that public key to your Git provider:

Then verify from your terminal:

ssh -T git@github.com\nssh -T git@gitlab.com\nssh -T git@bitbucket.org

SSH host aliases

GitGuise uses SSH aliases like github-work or github-personal. Each alias maps to a specific key.

# Example block in ~/.ssh/config\nHost github-work\n HostName github.com\n User git\n IdentityFile ~/.ssh/id_ed25519_work

These aliases are the “secret sauce” behind consistent identity selection.

Cloning repos (SSH)

Clone using the profile alias format:

git clone git@github-work:your-work-username/repo.git\n# or\ngit clone git@github-personal:your-personal-username/repo.git

If you have a HTTPS URL, convert it by replacing the host:

https://github.com/OWNER/REPO.git\n→\ngit@github-work:OWNER/REPO.git

Existing repos (app & terminal)

Already cloned a repo with HTTPS, or the wrong SSH key? Assign a GitGuise profile so remotes and local git identity stay consistent.

Prerequisites: at least one profile with an SSH key added to GitHub, and ssh -T git@<alias> succeeds.

Option A — App (best for many repos)

  1. Open GitGuise → Repos
  2. Click Scan Folder and pick the parent folder that contains your projects
  3. Find the repo (filter by Unknown if it’s not linked yet)
  4. Click Switch Profile → choose the identity → confirm

GitGuise will for that repo:

  • Set local user.email and user.name
  • Rewrite origin to git@<alias>:OWNER/REPO.git

Then verify in the card (or in a terminal):

git remote get-url origin\n# should look like: git@github-work:OWNER/REPO.git

Option B — Terminal (manual)

Inside the repo, check what you’re on today:

git remote -v\ngit config user.email\ngit config user.name

Point origin at the profile alias (keep the real OWNER — org or username):

git remote set-url origin git@github-work:OWNER/REPO.git

Set the repo-local identity to match that profile:

git config user.email \"you@company.com\"\ngit config user.name \"your-github-username\"

Option C — Terminal (push hook)

If Auto-detect on push is enabled in Settings → Hooks, you can fix an existing HTTPS/unknown remote by simply pushing:

git push

When the remote isn’t a known alias, GitGuise opens an interactive selector in the terminal. Pick the profile — it sets local identity and rewrites origin for you.

Org / fork remotes: keep OWNER as the org or upstream owner in the URL (e.g. git@github-work:acme/api.git). Don’t force your personal username into the path unless the repo lives under your account.

Push flow (auto-detect)

If the Auto-detect on push hook is enabled, it will:

  • Read your repo’s origin remote
  • If it contains a known alias (e.g. github-work), GitGuise ensures the right user.email/user.name is set
  • If the remote is HTTPS or unknown, it shows an interactive selector in the terminal
git push

git init & git remote add

If enabled, GitGuise wraps these commands:

  • git init: prompts which identity the repo belongs to, then sets local git config
  • git remote add: if you paste a GitHub HTTPS URL, it can convert it into the correct SSH alias format
git init\n\ngit remote add origin https://github.com/OWNER/REPO.git

Disable / remove hooks

Open GitGuise → Settings → Hooks.

  • Turn toggles off, then click Re-apply hooks
  • Or click Remove all hooks to fully uninstall

Verify setup

Test SSH for a profile alias:

ssh -T git@github-work

Expected output includes: You've successfully authenticated (or a “Hi …” message).

Verify a repo uses the right alias:

git remote get-url origin\n# should start with: git@github-...

Troubleshooting

Windows: GitGuise requires Git for Windows (Git Bash) to run shell commands. Install from:

https://git-scm.com/download/win

SSH issues: ensure your public key is added to GitHub and that ssh -T git@<alias> succeeds.

Wrong account on push: confirm your remote is using the expected alias:

git remote get-url origin

Fallback selector keeps appearing: your remote may be HTTPS. Convert it:

git remote set-url origin git@github-work:OWNER/REPO.git