DOCSEARCHbyAlgolia
Submit Docs

gita

repository·master·Indexed 23 days ago

https://github.com/nosarthur/gita

A command-line tool for managing multiple Git repositories simultaneously. Gita allows users to view the status of many repositories side-by-side, execute Git or shell commands across groups of repositories asynchronously, and define custom delegating sub-commands via JSON. It features a 'Superman mode' for arbitrary Git commands, a 'Shell mode' for shell commands, and context management to scope operations to specific repository subsets.

Tokens
3.9K
Snippets
7
Records
21
Agent score
84%

What's inside gita

  1. Overview of Gita core functionality

    master

    Gita is a command-line tool designed to manage multiple Git repositories. It provides two primary capabilities:

    1. Status Visualization: Displays status information for multiple repositories side-by-side, including branch names, edit status (staged, unstaged, untracked), and commit messages.
    2. Batch Git Proxy: Acts as a proxy to execute Git commands across multiple repositories (or specific groups/repos) from any directory.

    Status Indicators

    Local/Remote Relationship Colors:

    • Green: Local and remote are in sync.
    • Red: Local and remote have diverged.
    • Yellow: Local is behind remote (suitable for merge).
    • White: No remote specified for local.
    • Purple: Local is ahead of remote (suitable for push).

    Edit Status Symbols:

    • +: Staged
    • *: Unstaged
    • ?: Untracked

  2. Understand the gita command structure

    master

    The gita CLI is organized into three types of sub-commands that allow you to manage multiple repositories and execute git commands across them:

    1. Bookkeeping: Used to manage the list of repositories tracked by gita or to display repository information (e.g., add, ll).
    2. Delegating: Used to run pre-configured git commands or aliases across one or more repositories.
    3. super (Superman mode): Used to delegate arbitrary git commands or aliases to specific repositories.

    Command Syntax

    Most bookkeeping and delegating sub-commands follow these patterns:

    • gita <sub-command> <repo-name(s)> (requires specific repos)
    • gita <sub-command> [repo-name(s)] (optional repos, often applies to all)

    Specific Syntax Exceptions:

    • gita ll: Lists all managed repositories.
    • gita add <repo-path(s)>: Adds new repository paths to gita.
    • gita super [repo-name(s)] <any-git-command-with-options>: Runs an arbitrary git command on the specified repositories.

  3. How gita executes git commands

    master

    Gita executes git commands using either subprocess or asyncio to enable batch operations across multiple repositories from any working directory.

    • Single Repository/Synchronous: If you provide only one repository as input, or if a sub-command does not support asynchronous execution, gita uses standard subprocess calls.
    • Batch Mode (Asynchronous): When executing commands across multiple repositories, gita uses asyncio to run the commands in parallel for better efficiency.

  4. Define repo groups and contexts

    master

    You can group related repositories together to execute commands on the entire group at once. Once a group is defined, you can set it as your current 'context' so that subsequent gita commands are automatically scoped to that group without needing to specify the group name.

    Managing Groups

    • Add a group: gita group add <repo1> <repo2> -n <group-name>
    • List group members: gita ll <group-name>
    • Run command on group: gita <command> <group-name> (e.g., gita pull my-group)

    Managing Context

    • Set a specific group as context: gita context <group-name>
    • Set auto-context: gita context auto. In this mode, the context is automatically determined by the current working directory (CWD). The context becomes the group whose member repository path contains your CWD.
    • Remove context: gita context none

    Automatic Hierarchical Groups

    Use gita add -a <directory> to recursively add repositories within a directory and automatically generate hierarchical groups based on the folder structure.

    gita group add repo1 repo2 -n my-group
gita ll my-group
gita pull my-group

gita context my-group
gita ll
gita pull

gita context auto

gita context none

gita add -a src

  5. Delegate Git commands to multiple repos

    master

    Gita allows you to run Git commands across multiple repositories or groups. Commands follow two patterns:

    1. gita <sub-command> [repo-name(s) or group-name(s)]: If no repo/group is provided, the command applies to all repos. (Note: fetch and pull default to all repos).
    2. gita <sub-command> <repo-name(s) or groups-name(s)>: Applies the command only to the specified targets.

    When running commands on multiple repositories, Gita executes them asynchronously (except for log, difftool, and mergetool which require user interaction).

  6. Add user-defined sub-commands via JSON

    master

    You can extend gita by defining custom delegating sub-commands in $XDG_CONFIG_HOME/gita/cmds.json (typically ~/.config/gita/cmds.json). These commands can shadow default ones if names collide.

    Configuration Options

    • cmd: The actual command to execute.
    • help: Description for the command.
    • disable_async: Set to true to prevent asynchronous execution (useful for interactive tools).
    • allow_all: Set to true to allow the command to apply to all repositories in the current context if no specific repository name is provided (similar to gita fetch).
    • shell: Set to true to run the command in shell mode.

    Using Git Aliases

    If you have a Git alias defined in your .gitconfig, you can wrap it in a gita command by referencing it in the cmd field.

    {
  "stat": {
    "cmd": "git diff --stat",
    "help": "show edit statistics"
  },
  "difftool": {
    "cmd": "git difftool",
    "disable_async": true,
    "help": "show differences using a tool"
  },
  "comaster": {
    "cmd": "checkout master",
    "allow_all": true,
    "help": "checkout the master branch"
  },
  "fetchcrt": {
    "cmd": "git rev-parse --abbrev-ref HEAD | xargs git fetch --prune upstream",
    "allow_all": true,
    "shell": true,
    "help": "fetch current branch only"
  },
  "cod": {
    "cmd": "git cod",
    "allow_all": true,
    "help": "check out default branch"
  }
}

  7. Customize gita ll display (Colors, Info, and Symbols)

    master

    The gita ll command can be customized in three ways:

    1. Color Scheme

    To change the colors used for local/remote relationship status, use: gita color set <situation> <color> Configuration is stored in $XDG_CONFIG_HOME/gita/color.csv. Use gita color to view the default scheme and available colors.

    2. Information Items

    To change which columns are displayed in gita ll, edit $XDG_CONFIG_HOME/gita/info.csv. Example content: branch,commit_msg,commit_time. Use gita info to see currently used and unused items.

    3. Status Symbols

    To override the symbols used for git status (e.g., dirty, staged, untracked), create or edit $XDG_CONFIG_HOME/gita/symbols.csv. Only define the symbols you wish to change.

    Default Symbols Reference: dirty,staged,untracked,stashed,local_ahead,remote_ahead,diverged,in_sync,no_remote *,+,?,$,↑,↓,⇕,,∅

  8. Add repositories to Gita

    master

    Before using Gita, you must add your repositories to its management list. You can add individual paths, recursive directories, or bare repositories.

    • gita add <repo-path(s)> [-g <groupname>]: Add specific repositories, optionally assigning them to a group.
    • gita add -a <repo-parent-path(s)>: Recursively add all repositories within a parent path and automatically generate hierarchical groups.
    • gita add -r <repo-parent-path(s)>: Recursively add all repositories within a parent path.
    • gita add -b <bare-repo-path(s)>: Add bare repositories.

  9. Install Gita

    master

    You can install Gita using pip3. For development purposes, you can install it in editable mode.

    Standard installation:

    pip3 install -U gita

    Development installation:

    pip3 install -e <gita-source-folder>

    If the gita command is not recognized after installation, add the following alias to your .bashrc:

    alias gita="python3 -m gita"

    Note: Windows users may need additional configuration to support ANSI VT100 codes for colored output in PowerShell.

  10. Requirements for running Gita

    master

    To run gita, ensure your environment meets the following:

    • Python: Version 3.6 or higher (required for f-strings and asyncio).
    • Git: An installed version of Git. The tool uses subprocess to execute git commands; while it works with various versions (e.g., 1.8.3.1, 2.17.2, 2.20.1), ensure your version is compatible with your workflow.

  11. Execute Git commands in Superman mode

    master

    Superman mode allows you to proxy any Git command or alias to one or more repositories or groups.

    Syntax: gita super [repo-name(s) or group-name(s)] <any-git-command-with-or-without-options>

    Examples:

    • gita super checkout master: Switches all repositories (or the specified group/repos) to the master branch.
    • gita super frontend-repo backend-repo commit -am 'implement a new feature': Runs the specified commit command on both frontend-repo and backend-repo.
    gita super checkout master

  12. Customize repository info display

    master

    Gita allows you to add custom information items to the gita ll output.

    1. Define Data: Edit $XDG_CONFIG_HOME/gita/info.csv (typically ~/.config/gita/info.csv) to define your custom info items.
    2. Implement Logic: Create a directory named extra_info_items in your config directory. In $XDG_CONFIG_HOME/gita/extra_repo_info.py, map the info item name to a Python function that accepts a repository path as a string.

    Example extra_repo_info.py implementation:

    def get_delim(path: str) -> str:
    return '|'

extra_info_items = {'delim': get_delim}

    After implementation, your new items will appear in the unused section of gita info until they are properly integrated.