Home

Awesome

PyPi version Build Status codecov licence PyPI - Downloads Gitter Chinese

 _______________________________
(  ____ \__   __|__   __(  ___  )
| (    \/  ) (     ) (  | (   ) |
| |        | |     | |  | (___) |
| | ____   | |     | |  |  ___  |
| | \_  )  | |     | |  | (   ) |
| (___) |__) (___  | |  | )   ( |
(_______)_______/  )_(  |/     \|   v0.16

Gita: a command-line tool to manage multiple git repos

This tool has two main features

gita screenshot

In this screenshot, the gita ll command displays the status of all repos. The gita remote dotfiles command translates to git remote -v for the dotfiles repo, even though we are not in the repo. The gita fetch command fetches from all repos and two of them have updates. To see the pre-defined commands, run gita -h or take a look at cmds.json. To add your own commands, see the customization section. To run arbitrary git command, see the superman mode section. To run arbitrary shell command, see the shell mode section.

I also made a youtube video to demonstrate the common usages Img alt text

The branch color distinguishes 5 situations between local and remote branches:

colormeaning
whitelocal has no remote
greenlocal is the same as remote
redlocal has diverged from remote
purplelocal is ahead of remote (good for push)
yellowlocal is behind remote (good for merge)

The choice of purple for ahead and yellow for behind is motivated by blueshift and redshift, using green as baseline. You can change the color scheme using the gita color command. See the customization section.

The additional status symbols denote

symbolmeaning
+staged changes
*unstaged changes
?untracked files/folders
$stashed contents

The bookkeeping sub-commands are

The git delegating sub-commands are of two formats

They translate to git <sub-command> for the corresponding repos. By default, only fetch and pull take optional input. In other words, gita fetch and gita pull apply to all repos. To see the pre-defined sub-commands, run gita -h or take a look at cmds.json. To add your own sub-commands or override the default behaviors, see the customization section. To run arbitrary git command, see the superman mode section.

If more than one repos are specified, the git command runs asynchronously, with the exception of log, difftool and mergetool, which require non-trivial user input.

Repo configuration global is saved in $XDG_CONFIG_HOME/gita/repos.csv (most likely ~/.config/gita/repos.csv) or if you prefered at project configuration add environment variable GITA_PROJECT_HOME.

Installation

To install the latest version, run

pip3 install -U gita

If you prefer development mode, download the source code and run

pip3 install -e <gita-source-folder>

In either case, calling gita in terminal may not work, then put the following line in the .bashrc file.

alias gita="python3 -m gita"

Windows users may need to enable the ANSI escape sequence in terminal for the branch color to work. See this stackoverflow post for details.

Auto-completion

Bash

Download .gita-completion.bash and source it in shell.

Zsh

There are 2 options :

<a name='superman'></a> Superman mode

The superman mode delegates any git command or alias. Usage:

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

Here repo-name(s) or group-name(s) are optional, and their absence means all repos. For example,

<a name='shell'></a> Shell mode

The shell mode delegates any shell command. Usage:

gita shell [repo-name(s) or group-name(s)] <any-shell-command>

Here repo-name(s) or group-name(s) are optional, and their absence means all repos. For example,

<a name='custom'></a> Customization

define repo group and context

When the project contains several independent but related repos, we can define a group and execute gita command on this group. For example,

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

To save more typing, one can set a group as context, then any gita command is scoped to the group

gita context my-group
gita ll
gita pull

The most useful context maybe auto. In this mode, the context is automatically determined from the current working directory (CWD): the context is the group whose member repo's path contains CWD. To set it, run

gita context auto

To remove the context, run

gita context none

It is also possible to recursively add repos within a directory and generate hierarchical groups automatically. For example, running

gita add -a src

on the following folder structure

src
├── project1
│   ├── repo1
│   └── repo2
├── repo3
├── project2
│   ├── repo4
│   └── repo5
└── repo6

gives rise to 3 groups:

src:repo1,repo2,repo3,repo4,repo5,repo6
src-project1:repo1,repo2
src-project2:repo4,repo5

add user-defined sub-command using json file

Custom delegating sub-commands can be defined in $XDG_CONFIG_HOME/gita/cmds.json (most likely ~/.config/gita/cmds.json) And they shadow the default ones if name collisions exist.

Default delegating sub-commands are defined in cmds.json. For example, gita stat <repo-name(s)> is registered as

"stat":{
  "cmd": "git diff --stat",
  "help": "show edit statistics"
}

which executes git diff --stat for the specified repo(s).

To disable asynchronous execution, set disable_async to be true. See the difftool example:

"difftool":{
  "cmd": "git difftool",
  "disable_async": true,
  "help": "show differences using a tool"
}

If you want a custom command to behave like gita fetch, i.e., to apply to all repos when no repo is specified, set allow_all to be true. For example, the following snippet creates a new command gita comaster [repo-name(s)] with optional repo name input.

"comaster":{
  "cmd": "checkout master",
  "allow_all": true,
  "help": "checkout the master branch"
}

Any command that runs in the superman mode mode or the shell mode can be defined in this json format. For example, the following command runs in shell mode and fetches only the current branch from upstream.

"fetchcrt":{
  "cmd": "git rev-parse --abbrev-ref HEAD | xargs git fetch --prune upstream",
  "allow_all": true,
  "shell": true,
  "help": "fetch current branch only"
}

customize the local/remote relationship coloring displayed by the gita ll command

You can see the default color scheme and the available colors via gita color. To change the color coding, use gita color set <situation> <color>. The configuration is saved in $XDG_CONFIG_HOME/gita/color.csv.

customize information displayed by the gita ll command

You can customize the information displayed by gita ll. The used and unused information items are shown with gita info, and the configuration is saved in $XDG_CONFIG_HOME/gita/info.csv.

For example, the default setting corresponds to

branch,commit_msg,commit_time

Here branch includes both branch name and status. The status symbols are similar to the ones used in spaceship-prompt.

To customize these symbols, add a file in $XDG_CONFIG_HOME/gita/symbols.csv. The default settings corresponds to

dirty,staged,untracked,local_ahead,remote_ahead,diverged,in_sync,no_remote
*,+,?,↑,↓,⇕,,∅

Only the symbols to be overridden need to be defined. You can search unicode symbols here.

customize git command flags

One can set custom flags to run git commands. For example, with

gita flags set my-repo --git-dir=`gita ls dotfiles` --work-tree=$HOME

any git command/alias triggered from gita on dotfiles will use these flags. Note that the flags are applied immediately after git. For example, gita st dotfiles translates to

git --git-dir=$HOME/somefolder --work-tree=$HOME status

running from the dotfiles directory.

This feature was originally added to deal with bare repo dotfiles.

Requirements

Gita requires Python 3.6 or higher, due to the use of f-string and asyncio module.

Under the hood, gita uses subprocess to run git commands/aliases. Thus the installed git version may matter. I have git 1.8.3.1, 2.17.2, and 2.20.1 on my machines, and their results agree.

Tips

effectshell command
enter <repo> directorycd `gita ls <repo>`
delete repos in <group>gita group ll <group> | xargs gita rm

Contributing

To contribute, you can

Read this article if you have never contribute code to open source project before.

Chat room is available on Join the chat at https://gitter.im/nosarthur/gita

To run tests locally, simply pytest in the source code folder. Note that context should be set as none. More implementation details are in design.md. A step-by-step guide to reproduce this project is here.

You can also sponsor me on GitHub. Any amount is appreciated!

Other multi-repo tools

I haven't tried them but I heard good things about them.