Gity

gity is a lightweight Python automation tool designed for developers who manage multiple Git repositories across their local machine. Instead of navigating into every directory individually to check for uncommitted changes, pull updates, or fetch remote branches, gity scans your project directories and executes Git commands concurrently across all of them at once.

It also includes a built-in "jump" utility to instantly teleport your shell to any repository directory by typing a short command.

---

Features & Use Cases

• Bulk Git Status: Instantly see which repositories have uncommitted changes or untracked files.
• Bulk Fetch & Pull: Keep all your local project forks and branches up-to-date with a single command.
• Smart & Customizable Repository Search: Searches standard developer directories up to a configurable recursion depth (default is 3 levels), or scans your entire home directory on demand.
• Dynamic Search Paths: Save or delete specific paths to fully customize where Gity looks for your repositories.
• Submodule Tracking Support: Optionally include or exclude modern Git submodules in your automated scans.
• The "Jump" Feature (jp): Forget deep nesting paths. Quickly jump directly into any repository just by typing jp <repo-name>.

---

Installation & Setup

To make gity available as a global command on your system, follow these steps:

1. Copy the Script

Save the script as gity (no .py extension) in a directory that is in your system's $PATH (e.g., /usr/local/bin for system-wide access, or ~/.local/bin for your user only).

2. Make it Executable

Open your terminal and run:

chmod +x /usr/local/bin/gity

(If saving to /usr/local/bin, you may need to prepend sudo).

3. Verify Installation

Ensure it runs properly by checking the help menu:

gity --help

---

CLI Options & Usage

usage: gity [-h] [-f] [-p] [-l] [-a] [-s SAVE_PATH] [-d DELETE_PATH]
            [-g GET_PATH] [-j] [--search-paths]
            --set-max-depth SET_MAX_DEPTH]
            --include-submodules INCLUDE_SUBMODULES] [--view-config]
            [-v]

Run git status on all local repositories at once. Without arguments, Gity will search directories specified in your default search paths up to the maximum recursion depth and execute the status check.

Command Flags

Flag	Long Flag	Argument	Description
-h	--help	None	Show the help message and exit.
-f	--fetch	None	Execute git fetch on all repos found by Gity.
-p	--pull	None	Execute git pull on all repos found by Gity.
-l	--list	None	List all repositories Gity found in the current home directory.
-a	--all	None	Recursively search the entire home directory (~/) rather than default directories.
-s	--save-path	SAVE_PATH	Save a new directory to the default search paths.
-d	--delete-path	DELETE_PATH	Remove a directory from the default search paths.
-g	--get-path	GET_PATH	Prints the path for a specified repository name (used for jump).
-j	--jump-setup	None	Create an alias/shell function to use the jump shortcut feature.
	--search-paths	None	Show search paths Gity will use when no arguments are given.
	--set-max-depth	INT	Set the max # recursion levels to search (default is 3).
	--include-submodules	TRUE/FALSE	Set config to include/exclude submodules in Gity output (default is false; only recognizes modern submodules with .git files).
	--view-config	None	Print current Gity configuration settings and exit.
-v	--version	None	Print version info and exit.

Examples

Check status of all repositories in your default search paths:

gity

Pull updates for all repositories across your entire home directory:

gity -a -p

Add a new directory to your permanent search paths:

gity -s ~/development/work

Configure Gity to include submodules and change search depth:

gity --include-submodules TRUE
gity --set-max-depth 5

View your active configuration paths and settings:

gity --view-config
gity --search-paths

---

Setting Up the 'Jump' (jp) Feature

The "Jump" feature allows you to type jp <repository-name> from anywhere in your terminal to instantly change your current directory (cd) to that repository and run a git status on it.

Automatic Setup

1. Run the setup flag built into the script:

gity -j

2. Reload your shell configuration:

source ~/.bashrc

How It Works Behind the Scenes

Because a standalone Python script executes in a subshell, it cannot change the directory of your parent terminal session directly. The -j flag appends a custom shell function to your shell configuration file (e.g., ~/.bashrc):

jp() { cd "$(gity -g "$@")" && git status; }

When you type jp my-repo, the shell function queries gity -g my-repo to find the exact absolute path (checking the .git/config remote URL first, then falling back to folder names) and passes that path directly to the shell's native cd command.