gamon

README

gamon

---

Gamon is a command line tool that helps with managing multiple GitHub accounts on one machine.

Right now, it's main functionality is switching the active gh account based on your current working directory.

Table of Contents

• Prerequisites
• Dependencies
• Installation
• Set up
• Usage
• Documentation
• License

Prerequisites

Before you install this software, make sure you have a compatible shell installed. We currently support bash and zsh, and plan to support fish in the future.

	MacOS	Linux
Shell	bash / zsh	bash / zsh
Future Support	fish	fish

Dependencies

This software depends on the following software:

Build Dependencies

Application	Link
Go	Link to Go

Runtime Dependencies

Application	Link
gh	Link to gh
yq	Link to yq

gh is GitHub’s official command line tool. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code.

yq is a portable command-line YAML processor. It uses jq-like syntax but works with yaml files as well as json.

Installation

Below are the two simplest ways to install the gamon binary, gam.

Check out manual installation for more detailed installation instructions.

Homebrew

If you're on macOS, you can use Homebrew:

brew tap peter-bread/gamon
brew install gamon

Homebrew will manage dependencies automatically.

Not tested yet, but this might work on Linux if you are using Linuxbrew.

Pre-built Binaries

Ensure you have installed the runtime dependencies.

You can use the installation script to download, extract and install the binary.

This script downloads the pre-built binary, moves it to ~/.gamon/bin, and performs other necessary setup tasks.

Before using this script, please ensure you review and understand the operations it performs. This is to ensure that it aligns with your intended use and doesn't cause unintended effects.

You will be prompted to add ~/.gamon/bin to PATH in your .bashrc or zshrc.

For the latest release:

curl -fsSL https://raw.githubusercontent.com/peter-bread/gamon/main/scripts/install_binary.sh | bash

For a specific version:

curl -fsSL https://raw.githubusercontent.com/peter-bread/gamon/main/scripts/install_binary.sh | bash -s -- X

where X is the major version you wish to install.

Note: The versioning scheme used is X.Y.Z. When you specify X in the command above, the script will install the latest release within that major version.

See manual installation for more installation options.

Set up

See this guide for a setting up the required file structure.

In future releases, I hope to automate much of the set up process.

Or change it entirely...

You need to set GAM_REPO_ROOT_DIR, the path where all of your git repositories will be stored.

This is illustrated below:

"$GAM_REPO_ROOT_DIR/"
|-- personal/
|   |-- myrepo123/
|-- work/
|   |-- project1/
|   |-- project2/
|
| ...

To set GAM_REPO_ROOT_DIR, add the following line to your .zshrc or .bashrc file:

export GAM_REPO_ROOT_DIR="/path/to/repo/root/directory"

Replace "/path/to/repo/root/directory" with the actual path to your repository root directory.

Then, to enable automatic account switching based on the repository you're working with, add the following line to your .zshrc or .bashrc file:

source <(gam script)

This will run the gam script command every time you start a new shell session, setting up the necessary environment for automatic account switching.

Usage

After settimg up gam as described in the set up section, you can start using it to manage your GitHub accounts.

gam uses the GAM_REPO_ROOT_DIR environment variable to determine which GitHub account to use based on the current repository. When you navigate to a directory within GAM_REPO_ROOT_DIR and run a GitHub CLI command, gam will automatically switch to the account associated with that directory.

Remember to source the gam script in each new shell session to enable automatic account switching:

source <(gam script)

Documentation

• Manual Installation
• Commands
• Updating
• Uninstalling

License

This project is licensed under the terms of the MIT license. See the LICENSE file for the full license text.

Documentation

Overview

Copyright © 2024 Peter Sheehan <github.com/peter-bread>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.