_______________________________
( ____ \__ __|__ __( ___ )
| ( \/ ) ( ) ( | ( ) |
| | | | | | | (___) |
| | ____ | | | | | ___ |
| | \_ ) | | | | | ( ) |
| (___) |__) (___ | | | ) ( |
(_______)_______/ )_( |/ \| v0.16
This tool has two main features
- display the status of multiple git repos such as branch, modification, commit message side by side
- (batch) delegate git commands/aliases and shell commands on repos from any working directory
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
The branch color distinguishes 5 situations between local and remote branches:
| color | meaning |
|---|---|
| white | local has no remote |
| green | local is the same as remote |
| red | local has diverged from remote |
| purple | local is ahead of remote (good for push) |
| yellow | local 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
| symbol | meaning |
|---|---|
+ |
staged changes |
* |
unstaged changes |
? |
untracked files/folders |
$ |
stashed contents |
The bookkeeping sub-commands are
gita add <repo-path(s)> [-g <groupname>]: add repo(s) togita, optionally into an existing groupgita add -a <repo-parent-path(s)>: add repo(s) in <repo-parent-path(s)> recursively and automatically generate hierarchical groups. See the customization section for more details.gita add -b <bare-repo-path(s)>: add bare repo(s) togita. See the customization section for more details on setting custom worktree.gita add -r <repo-parent-path(s)>: add repo(s) in <repo-parent-path(s)> recursivelygita clear: remove all groups and reposgita clone <URL>: clone repo fromURLat current working directorygita clone <URL> -C <directory>: change todirectoryand then clone repogita clone -f <config-file>: clone repos inconfig-file(generated bygita freeze) to current directory.gita clone -p -f <config-file>: clone repos inconfig-fileto prescribed paths.gita context: context sub-commandgita context: show current contextgita context <group-name>: set context togroup-name, all operations then only apply to repos in this groupgita context auto: set context automatically according to the current working directorygita context none: remove context
gita color: color sub-commandgita color [ll]: Show available colors and the current coloring schemegita color reset: Reset to the default coloring schemegita color set <situation> <color>: Use the specified color for the local-remote situation
gita flags: flags sub-commandgita flags set <repo-name> <flags>: add customflagsto repogita flags [ll]: display repos with custom flags
gita freeze: print information of all repos such as URL, name, and path. Use withgita clone.gita group: group sub-commandgita group add <repo-name(s)> -n <group-name>: add repo(s) to a new or existing groupgita group [ll]: display existing groups with reposgita group ls: display existing group namesgita group rename <group-name> <new-name>: change group namegita group rm <group-name(s)>: delete group(s)gita group rmrepo <repo-name(s)> -n <group-name>: remove repo(s) from existing group
gita info: info sub-commandgita info [ll]: display the used and unused information itemsgita info add <info-item>: enable information itemgita info rm <info-item>: disable information item
gita ll: display the status of all reposgita ll <group-name>: display the status of repos in a groupgita ll -g: display the repo summaries by groupsgita ls: display the names of all reposgita ls <repo-name>: display the absolute path of one repogita rename <repo-name> <new-name>: rename a repogita rm <repo-name(s)>: remove repo(s) fromgita(won't remove files on disk)gita -v: display gita version
The git delegating sub-commands are of two formats
gita <sub-command> [repo-name(s) or group-name(s)]: optional repo or group input, and no input means all repos.gita <sub-command> <repo-name(s) or groups-name(s)>: required repo name(s) or group name(s) input
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.
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.
You can download the generated auto-completion file in the following locations for your specific shell. Alternatively, if you have installed argcomplete on your system, you can also directly run eval "$(register-python-argcomplete gita -s SHELL)" (e.g. SHELL as bash/zsh) in your dotfile.
Download .gita-completion.bash and source it in shell.
There are 2 options :
- .gita-completion.zsh. Use the help of gita command to display options. It uses the bash completion system for zsh.
Add
autoload -U +X bashcompinit && bashcompinitin .zshrc and source the zsh file - _gita.
Completion more Zsh style. Copy it in a folder and add this folder path in
FPATHvariable. This completion file doesn't take account to command from cmds.json
Download gita.fish and place it in ~/.config/fish/completions/
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,
gita super checkout masterputs all repos on the master branchgita super frontend-repo backend-repo commit -am 'implement a new feature'executesgit commit -am 'implement a new feature'forfrontend-repoandbackend-repo
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,
gita shell lllists contents for all reposgita shell repo1 repo2 mkdir docscreate a new directorydocsinrepo1andrepo2gita shell "git describe --abbrev=0 --tags | xargs git checkout": check out the latest tag for all repos
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
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"
}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.
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.
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.
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.
| effect | shell command |
|---|---|
enter <repo> directory |
cd `gita ls <repo>` |
delete repos in <group> |
gita group ll <group> | xargs gita rm |
To contribute, you can
- report/fix bugs
- request/implement features
- star/recommend this project
Read this article if you have never contribute code to open source project before.
Chat room is available on
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!
I haven't tried them but I heard good things about them.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent