Git & GitHub Setup

chro uses Git for version control and GitHub for collaboration. This guide covers installation and SSH key setup for both platforms.

Check Existing Installation

First, check if Git is already installed:

git --version

If Git is installed, you’ll see a version number. Otherwise, follow the installation instructions below.

---

macOS

Option 1: Xcode Command Line Tools (Recommended)

The easiest way to get Git on macOS:

xcode-select --install

A dialog will appear. Click “Install” and wait for completion.

Option 2: Homebrew

If you have Homebrew installed:

brew install git

Verify Installation

git --version  # Should show git version 2.x.x

---

Windows

Option 1: winget (Recommended)

Using the Windows Package Manager:

winget install Git.Git

Note: Restart your terminal after installation.

Option 2: Git for Windows Installer

1. Download from git-scm.com
2. Run the installer
3. Use default settings (recommended for beginners)
4. Ensure “Git from the command line and also from 3rd-party software” is selected

Verify Installation

Open a new terminal/PowerShell window:

git --version

---

Initial Git Configuration

Configure your identity (required for commits):

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Set default branch name to main:

git config --global init.defaultBranch main

Verify your configuration:

git config --list

---

GitHub Account Setup

If you don’t have a GitHub account:

1. Go to github.com
2. Click “Sign up”
3. Follow the registration process
4. Verify your email address

---

SSH Key Setup (Recommended)

SSH keys provide secure, password-less authentication with GitHub.

Generate SSH Key

macOS / Linux / Windows (Git Bash or WSL):

ssh-keygen -t ed25519 -C "[email protected]"

When prompted:

• Press Enter to accept the default file location
• Enter a passphrase (recommended) or press Enter for no passphrase

Windows (PowerShell):

ssh-keygen -t ed25519 -C "[email protected]"

Start SSH Agent

macOS:

eval "$(ssh-agent -s)"

Add to ~/.ssh/config (create if it doesn’t exist):

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Add your key:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Windows (PowerShell - Run as Administrator):

# Start the ssh-agent service
Get-Service -Name ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

# Add your key
ssh-add $env:USERPROFILE\.ssh\id_ed25519

Linux / WSL:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Add SSH Key to GitHub

1. Copy your public key:

macOS:

pbcopy < ~/.ssh/id_ed25519.pub

Windows (PowerShell):

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

Linux:

cat ~/.ssh/id_ed25519.pub
# Then manually copy the output

2. Add to GitHub:

1. Go to GitHub Settings > SSH Keys
2. Click “New SSH key”
3. Give it a descriptive title (e.g., “MacBook Pro 2024”)
4. Paste your key into the “Key” field
5. Click “Add SSH key”

Test Connection

ssh -T [email protected]

You should see:

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

---

Alternative: HTTPS with Personal Access Token

If you prefer HTTPS over SSH:

Create Personal Access Token

1. Go to GitHub Settings > Developer Settings > Personal Access Tokens
2. Click “Generate new token (classic)”
3. Give it a descriptive name
4. Select scopes: repo (full control of private repositories)
5. Click “Generate token”
6. Copy the token immediately (you won’t see it again)

Configure Git Credential Storage

macOS:

git config --global credential.helper osxkeychain

Windows:

git config --global credential.helper wincred

When you first push/pull, enter your GitHub username and use the token as your password.

---

Verify GitHub Connection

Test by cloning a repository:

# SSH (recommended)
git clone [email protected]:octocat/Hello-World.git

# Or HTTPS
git clone https://github.com/octocat/Hello-World.git

If successful, you’re ready to use Git with GitHub!

---

Troubleshooting

”Permission denied (publickey)”

• Ensure your SSH key is added to the agent: ssh-add -l
• Verify the key is added to GitHub: github.com/settings/keys
• Check you’re using the correct key: ssh -vT [email protected]

”Could not open a connection to your authentication agent”

Start the SSH agent:

eval "$(ssh-agent -s)"

Git asks for password on every push (HTTPS)

Configure credential storage:

# macOS
git config --global credential.helper osxkeychain

# Windows
git config --global credential.helper wincred

# Linux
git config --global credential.helper store

Line ending issues (Windows)

Configure Git to handle line endings:

git config --global core.autocrlf true

---

Next Steps

Once Git and GitHub are configured, proceed to:

• AI Coding Tools Setup - Install Claude Code or OpenAI Codex
• chro Installation - Install chro