Skip to content

get-started.md

Latest commit

 

History

History
129 lines (86 loc) · 3.72 KB

get-started.md

File metadata and controls

129 lines (86 loc) · 3.72 KB
icon lucide/rocket

Get Started

This guide will help you install gut and get it configured for your GitHub organization.

Installation

Download Pre-built Binaries

Download the latest nightly build for your platform:

Extract the archive and move the binary to somewhere on your $PATH.

Build from Source

If you prefer to build from source:

  1. Install Rust
  2. Clone the repository: 
    git clone https://github.com/divvun/gut.git
cd gut
  3. Build and install: 
    cargo install --path .

The gut binary will be installed to ~/.cargo/bin/.

Initial Setup

1. Create a GitHub Personal Access Token

gut needs a personal access token to interact with GitHub's API:

  1. Go to GitHub Settings > Personal Access Tokens
  2. Click "Generate new token (classic)"
  3. Give it a descriptive name (e.g., "gut CLI")
  4. Select the required scopes:
    • repo (Full control of private repositories)
    • admin:org (Full control of orgs and teams) - if managing organizations
    • delete_repo (Delete repositories) - if you need this capability
  5. Click "Generate token"
  6. Copy the token - you won't be able to see it again!

2. Initialize gut Configuration

Run the initialization command:

gut init -r <root-dir> -t <token>

Parameters:

  • <root-dir>: The directory where gut will store all cloned repositories

    • Repositories are organized as <root-dir>/<organization>/<repo-name>
    • Example: /Users/you/projects/repos

  • <token>: The GitHub personal access token you created in step 1

Example:

gut init -r ~/gut-repos -t ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This creates a configuration file in your system's config directory (e.g., ~/.config/gut/ on Linux/macOS).

3. Set a Default Owner (Optional)

To avoid specifying -o <owner> with every command, set a default:

gut set owner <owner-name>

For example:

gut set owner divvun

SSH Access (Optional)

By default, gut uses HTTPS for git operations. If you prefer SSH:

  1. Set up an SSH key for GitHub following these instructions
  2. When running gut init, the tool will detect your SSH setup

!!! note "Protocol Selection" The choice between HTTPS and SSH is made during initialization. HTTPS is recommended for simplicity, while SSH is useful if you have complex authentication requirements or use hardware security keys.

Verify Installation

Check that everything is working:

# View your configuration
gut show config

# List repositories in your organization
gut show repositories -o <org-name> -r ".*"

If these commands work, you're all set!

Next Steps

Now that gut is installed and configured, you can:

Getting Help

  • Run gut --help to see all available commands
  • Run gut <command> --help for help with a specific command
  • Check the GitHub issues for known problems
  • Review the USAGE.md file for additional examples