- 📜 Table of Contents
- 👋 Getting started
- 📟 Commands
- 💡 Tips
- 🗂 Custom Structures
- 🙌 Contributing
- 👥 Contributors
As you begin contributing to an increasing amount of GitHub repositories, you'll soon realize the effort it takes to organize and maintain them on your machine. fgh aims to solve this issue through the use of a CLI (command line interface) to automate the entire lifecycle of your cloned repos, saving you time and helping you scale! Below is a list of the most useful automation commands:
brew install gleich/homebrew-tap/fghYou can grab the binary from the latest release.
fgh remove, fgh clean, fgh ls, fgh pull, and fgh visualize can be tried out on your current repository structure with the addition of the -p flag. The value for this flag is the relative root path to the folder where all your git repos live. If we had the repo structure shown below and we were running fgh from ~ the root folder would be ./code/. This root folder is then passed into the command: fgh ls -p=./code/.
~
└─ code
├─ fgh
├─ dots
├─ turtle-site
└─ work
├─ super-secret-code
└─ website
Before using fgh, you'll need to give it access to your GitHub repos. Simply run fgh login to quickly get set up! fgh only uses this access to get metadata about the repo (e.g. main language, if private) and to clone the repo. fgh needs the full repo scope to access private repos.
If you need to use a GitHub custom access token, like a PAT, edit the secret configuration file. In Windows it is located in ~\.fgh\secrets.yml and ~/.config/fgh/secrets.yml in Linux and macOS. You should change/add the pat as seen below:
pat: <your token here>To configure other settings, run fgh configure for an interactive configuration experience.
To begin using fgh, you'll need to clone a repository, which you can do by running the following in a terminal window:
fgh clone <owner/name>OR
fgh clone <name> # if the repo is under your accountAll repositories are cloned into the following structure by default:
~
└─ github
└─ OWNER
└─ TYPE
└─ MAIN_LANGUAGE
└─ NAME
These names correspond to the following keywords:
OWNERis the owner of the repositoryTYPEis the type of the repository; one of the following:publicprivatetemplatearchiveddisabledmirrorfork
MAIN_LANGUAGEis The main language that the repository contains. If no language is detected,fghwill just set it toOtherNAMEis the name of the repository
If you would like to use a custom structure see the custom structures documentation. Usage of this command is as follows:
fgh clone <owner/name>If we were to run fgh clone gleich/fgh it would be cloned to ~/github/gleich/public/Go/fgh/ by default (~ being your home directory). Once cloned, this path will be copied to your clipboard automatically (this can be turned off with fgh configure or just by editing the config file directly).
NOTE: On Linux machines running the X Window System, this program requires the
xcliporxselpackages.
This structure can be somewhat difficult to navigate in the terminal using conventional methods such as the use of the cd command. Because of this, we created the fgh ls command and a way to use it with cd.
Would you like to add your existing repositories to the fgh structure? All you have to do run the following command and it will move every single git repo in that directory and all subdirectories into the structure:
fgh migrate <folder>An example would be:
fgh migrate code
This would migrate all git repos in the ./code folder into fgh's structure.
If any of a repository's fields are changed, such as its type, main language, owner, or name, the path to your local repository won't match.
Running fgh update will iterate over your local repositories and checks if any of them need updates. If they do, fgh will ask you if you want to move the entire repository to that new path.
For example, If I had this repository cloned and later decided to archive it, its path would change from ~/github/gleich/public/Go/fgh/ to ~/github/gleich/archived/Go/fgh/.
When you run this subcommand, fgh will check for the following on each repository:
- Has it modified locally in a certain amount of time?
By default, this "amount of time" is 2 months. However, it can be changed with a flag! See
fgh clean --helpfor more info. - Has the repository been deleted on GitHub?
If either of those conditions are met, fgh will ask you if you would like to remove the aforementioned repository. It'll additionally show you some information about the repository itself.
NOTE: This only removes the repo locally!
Remove a selected cloned repository. Usage is as follows:
fgh remove <owner/name>Get the path of a cloned repository. Usage is as follows:
fgh ls <owner/name>You may omit owner if you own the repository, or if there is only one cloned repository with the given name.
Pull all repos that don't have any non-pushed changes. Usage is as follows:
fgh pullVisualize all of the cloned repos in a table. Usage is as follows:
fgh visualizeAny command that takes <owner/name> as an argument allows you to leave off the owner if the repo is under your account. For example, I own this repo so I can just do
fgh clone fghinstead of
fgh clone gleich/fghNOTE: This only works in macOS and Linux
If you would like to easily use the output of fgh ls for cd just add the following snippet to your ~/.zshrc or ~/.bashrc:
# cd with fgh (https://github.com/gleich/fgh)
fcd() { cd "$(fgh ls "$@" 2>/dev/null)" || ( echo "Failed to find repository" && return 1; ) }If you're using Fish, add the following to your ~/.config/fish/config.fish:
function fcd --wraps "fgh ls"
if ! cd (fgh ls $argv) > /dev/null
echo "Failed to find repository"; return 1
end
endOnce you add that and reload your terminal you can simply run fcd <owner/name> instead of fgh ls <owner/name>, copying the output to your clipboard, typing cd, and pasting the output. Much easier!
You can add autocompletion for fgh by running one of the following commands based on your shell:
| Shell | Command |
|---|---|
| zsh | fgh completion zsh > "${fpath[1]}/_fgh" |
| fish | fgh completion fish > ~/.config/fish/completions/fgh.fish |
| bash (linux) | fgh completion bash > /etc/bash_completion.d/fgh |
| bash (macOS) | fgh completion bash > /usr/local/etc/bash_completion.d/fgh |
Thanks to the great work by @cjdenio fgh has a visual studio code extension! You can clone, open repos, and more right from vscode.
To clone over SSH instead of HTTPS, simply run fgh configure or set ssh: true in your ~/.config/fgh/config.yaml!
Not a fan of the default structure used by fgh? Don't worry, you can change it without losing any of fgh's automation! Configuring custom structures takes place in the general configuration file. This file is located in ~/.config/fgh/config.yaml on Linux or macOS and ~\.fgh\config.yaml on Windows (~ is your home directory). There are two parts to creating custom structures:
This is where the structure starts relative to your home folder. Make sure you use \ instead of / if you are on Windows. By default, the structure_root is github. Below is an example of what you would put in the general config file:
structure_root: 'Documents/code/'If we were to run fgh clone gleich/fgh with the config shown above it would be cloned to ~/Documents/code/gleich/public/Go/fgh.
By default, the home directory will be appended to the front of the path. If you like to turn this off add / for macOS/Linux or \ for Windows to the beginning of your path. Below is an example:
structure_root: '/code/github'If we were to run fgh clone gleich/fgh with the config shown above it would be cloned to /code/github/gleich/public/Go/fgh.
This is the structure used inside of the structure_root If you use the keywords shown in the clone structure it will automatically be replaced by the value for the repo and add the name of the repo to the end. Below is an example of what you would put in the general config file:
structure:
- OWNER
- repos
- MAIN_LANGUAGEIf we were to run fgh clone gleich/fgh with just the config shown above it would be cloned to ~/github/gleich/repos/Go/fgh.
Say we have the following config:
structure_root: 'code'
structure:
- OWNERIf we were to run fgh clone gleich/fgh it would clone the repo to ~/code/gleich/fgh.
Just run:
fgh migrate <old project root>Thank you for considering contributing to fgh! Before contributing, make sure to read the CONTRIBUTING.md file.