[](https://pypi.org/project/gita/)
[](https://travis-ci.org/nosarthur/gita)
[](https://codecov.io/gh/nosarthur/gita)
[](https://github.com/nosarthur/gita/blob/master/LICENSE)
[](https://pypistats.org/packages/gita)
[](https://gitter.im/nosarthur/gita?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[](https://github.com/nosarthur/gita/blob/master/doc/README_CN.md)
```
_______________________________
( ____ \__ __|__ __( ___ )
| ( \/ ) ( ) ( | ( ) |
| | | | | | | (___) |
| | ____ | | | | | ___ |
| | \_ ) | | | | | ( ) |
| (___) |__) (___ | | | ) ( |
(_______)_______/ )_( |/ \| v0.16
```
# Gita: a command-line tool to manage multiple git repos
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](https://github.com/nosarthur/gita/blob/master/gita/cmds.json).
To add your own commands, see the [customization section](#custom).
To run arbitrary `git` command, see the [superman mode section](#superman).
To run arbitrary shell command, see the [shell mode section](#shell).
I also made a youtube video to demonstrate the common usages
[](https://www.youtube.com/watch?v=ySWbwQcbhqI)
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](https://en.wikipedia.org/wiki/Blueshift) and [redshift](https://en.wikipedia.org/wiki/Redshift),
using green as baseline.
You can change the color scheme using the `gita color` command.
See the [customization section](#custom).
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) to `gita`, optionally into an existing group
- `gita add -a <repo-parent-path(s)>`: add repo(s) in <repo-parent-path(s)> recursively
and automatically generate hierarchical groups. See the [customization section](#custom) for more details.
- `gita add -b <bare-repo-path(s)>`: add bare repo(s) to `gita`. See the [customization section](#custom) for more details on setting custom worktree.
- `gita add -r <repo-parent-path(s)>`: add repo(s) in <repo-parent-path(s)> recursively
- `gita clear`: remove all groups and repos
- `gita clone <URL>`: clone repo from `URL` at current working directory
- `gita clone <URL> -C <directory>`: change to `directory` and then clone repo
- `gita clone -f <config-file>`: clone repos in `config-file` (generated by `gita freeze`) to current directory.
- `gita clone -p -f <config-file>`: clone repos in `config-file` to prescribed paths.
- `gita context`: context sub-command
- `gita context`: show current context
- `gita context <group-name>`: set context to `group-name`, all operations then only apply to repos in this group
- `gita context auto`: set context automatically according to the current working directory
- `gita context none`: remove context
- `gita color`: color sub-command
- `gita color [ll]`: Show available colors and the current coloring scheme
- `gita color reset`: Reset to the default coloring scheme
- `gita color set <situation> <color>`: Use the specified color for the local-remote situation
- `gita flags`: flags sub-command
- `gita flags set <repo-name> <flags>`: add custom `flags` to repo
- `gita flags [ll]`: display repos with custom flags
- `gita freeze`: print information of all repos such as URL, name, and path. Use with
`gita clone`.
- `gita group`: group sub-command
- `gita group add <repo-name(s)> -n <group-name>`: add repo(s) to a new or existing group
- `gita group [ll]`: display existing groups with repos
- `gita group ls`: display existing group names
- `gita group rename <group-name> <new-name>`: change group name
- `gita 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-command
- `gita info [ll]`: display the used and unused information items
- `gita info add <info-item>`: enable information item
- `gita info rm <info-item>`: disable information item
- `gita ll`: display the status of all repos
- `gita ll <group-name>`: display the status of repos in a group
- `gita ll -g`: display the repo summaries by groups
- `gita ls`: display the names of all repos
- `gita ls <repo-name>`: display the absolute path of one repo
- `gita rename <repo-name> <new-name>`: rename a repo
- `gita rm <repo-name(s)>`: remove repo(s) from `gita` (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](https://github.com/nosarthur/gita/blob/master/gita/cmds.json).
To add your own sub-commands or override the default behaviors, see the [customization section](#custom).
To run arbitrary `git` command, see the [superman mode section](#superman).
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](https://stackoverflow.com/questions/51680709/colored-text-output-in-powershell-console-using-ansi-vt100-codes) for details.
## Auto-completion
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.
### Bash
Download [.gita-completion.bash](https://github.com/nosarthur/gita/blob/master/.gita-completion.bash) and source it in shell.
### Zsh
There are 2 options :
- [.gita-completion.zsh](https://github.com/nosarthur/gita/blob/master/contrib.completion/zsh/.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 && bashcompinit` in .zshrc and source the zsh file
- [_gita](https://github.com/nosarthur/gita/blob/master/contrib.completion/zsh/_gita_).
Completion more Zsh style. Copy it in a folder and add this folder path in `FPATH` variable. This completion file doesn't take account to command from cmds.json
### Fish
Download [gita.fish](https://github.com/nosarthur/gita/tree/master/auto-completion/fish/gita.fish) and place it in `~/.config/fish/completions/`
## <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,
- `gita super checkout master` puts all repos on the master branch
- `gita super frontend-repo backend-repo commit -am 'implement a new feature'`
executes `git commit -am 'implement a new feature'` for `frontend-repo` and `backend-repo`
## <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,
- `gita shell ll` lists contents for all repos
- `gita shell repo1 repo2 mkdir docs` create a new directory `docs` in `repo1` and `repo2`
- `gita shell "git describe --abbrev=0 --tags | xargs git checkout"`: check out the latest tag for all repos
## <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](https://github.com/nosarthur/gita/blob/master/gita/cmds.json).
For example, `gita stat <repo-name(s)>` is registered as
```json
"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:
```json
"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.
```json
"comaster":{
"cmd": "checkout master",
"allow_all": true,
"help": "checkout the master branch"
}
```
Any command that runs in the [superman mode](#superman) mode or the
[shell mode](#shell) can be defined in this json format.
For example, the following command runs in shell mode and fetches only the
current branch from upstream.
```json
"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
```csv
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](https://spaceship-prompt.sh/sections/git/#Git-status-git_status).
To customize these symbols, add a file in `$XDG_CONFIG_HOME/gita/symbols.csv`.
The default settings corresponds to
```csv
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](https://www.compart.com/en/unicode/).
### 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](https://www.atlassian.com/git/tutorials/dotfiles).
## Requirements
Gita requires Python 3.6 or higher, due to the use of
[f-string](https://www.python.org/dev/peps/pep-0498/)
and [asyncio module](https://docs.python.org/3.6/library/asyncio.html).
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
| effect | shell command |
| ------------------------- | ---------------------------------------- |
| enter `<repo>` directory | `` cd `gita ls <repo>` `` |
| delete repos in `<group>` | `gita group ll <group> \| xargs gita rm` |
## Contributing
To contribute, you can
- report/fix bugs
- request/implement features
- star/recommend this project
Read [this article](https://www.dataschool.io/how-to-contribute-on-github/) if you have never contribute code to open source project before.
Chat room is available on [](https://gitter.im/nosarthur/gita?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
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](https://github.com/nosarthur/gita/blob/master/doc/design.md).
A step-by-step guide to reproduce this project is [here](https://nosarthur.github.io/side%20project/2019/05/27/gita-breakdown.html).
You can also sponsor me on [GitHub](https://github.com/sponsors/nosarthur). Any amount is appreciated!
## Other multi-repo tools
I haven't tried them but I heard good things about them.
- [myrepos](https://myrepos.branchable.com/)
- [repo](https://source.android.com/setup/develop/repo)
- [mu-repo](https://github.com/fabioz/mu-repo)
Raw data
{
"_id": null,
"home_page": "https://github.com/nosarthur/gita",
"name": "gita",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.6",
"maintainer_email": null,
"keywords": "git, manage multiple repositories, cui, command-line",
"author": "Dong Zhou",
"author_email": "zhou.dong@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/10/18/fe4eba560324f51df64d969f2e0fc93f1bb63ee67991b8eff598843b3777/gita-0.16.7.1.tar.gz",
"platform": "linux",
"description": "[](https://pypi.org/project/gita/)\n[](https://travis-ci.org/nosarthur/gita)\n[](https://codecov.io/gh/nosarthur/gita)\n[](https://github.com/nosarthur/gita/blob/master/LICENSE)\n[](https://pypistats.org/packages/gita)\n[](https://gitter.im/nosarthur/gita?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)\n[](https://github.com/nosarthur/gita/blob/master/doc/README_CN.md)\n\n```\n _______________________________\n( ____ \\__ __|__ __( ___ )\n| ( \\/ ) ( ) ( | ( ) |\n| | | | | | | (___) |\n| | ____ | | | | | ___ |\n| | \\_ ) | | | | | ( ) |\n| (___) |__) (___ | | | ) ( |\n(_______)_______/ )_( |/ \\| v0.16\n```\n\n# Gita: a command-line tool to manage multiple git repos\n\nThis tool has two main features\n\n- display the status of multiple git repos such as branch, modification, commit message side by side\n- (batch) delegate git commands/aliases and shell commands on repos from any working directory\n\n\n\nIn this screenshot, the `gita ll` command displays the status of all repos.\nThe `gita remote dotfiles` command translates to `git remote -v`\nfor the `dotfiles` repo, even though we are not in the repo.\nThe `gita fetch` command fetches from all repos and two of them have updates.\nTo see the pre-defined commands, run `gita -h` or take a look at\n[cmds.json](https://github.com/nosarthur/gita/blob/master/gita/cmds.json).\nTo add your own commands, see the [customization section](#custom).\nTo run arbitrary `git` command, see the [superman mode section](#superman).\nTo run arbitrary shell command, see the [shell mode section](#shell).\n\nI also made a youtube video to demonstrate the common usages\n[](https://www.youtube.com/watch?v=ySWbwQcbhqI)\n\nThe branch color distinguishes 5 situations between local and remote branches:\n\n| color | meaning |\n| ------ | ---------------------------------------- |\n| white | local has no remote |\n| green | local is the same as remote |\n| red | local has diverged from remote |\n| purple | local is ahead of remote (good for push) |\n| yellow | local is behind remote (good for merge) |\n\nThe choice of purple for ahead and yellow for behind is motivated by\n[blueshift](https://en.wikipedia.org/wiki/Blueshift) and [redshift](https://en.wikipedia.org/wiki/Redshift),\nusing green as baseline.\nYou can change the color scheme using the `gita color` command.\nSee the [customization section](#custom).\n\nThe additional status symbols denote\n\n| symbol | meaning |\n| ------ | ----------------------- |\n| `+` | staged changes |\n| `*` | unstaged changes |\n| `?` | untracked files/folders |\n| `$` | stashed contents |\n\nThe bookkeeping sub-commands are\n\n- `gita add <repo-path(s)> [-g <groupname>]`: add repo(s) to `gita`, optionally into an existing group\n- `gita add -a <repo-parent-path(s)>`: add repo(s) in <repo-parent-path(s)> recursively\n and automatically generate hierarchical groups. See the [customization section](#custom) for more details.\n- `gita add -b <bare-repo-path(s)>`: add bare repo(s) to `gita`. See the [customization section](#custom) for more details on setting custom worktree.\n- `gita add -r <repo-parent-path(s)>`: add repo(s) in <repo-parent-path(s)> recursively\n- `gita clear`: remove all groups and repos\n- `gita clone <URL>`: clone repo from `URL` at current working directory\n- `gita clone <URL> -C <directory>`: change to `directory` and then clone repo\n- `gita clone -f <config-file>`: clone repos in `config-file` (generated by `gita freeze`) to current directory.\n- `gita clone -p -f <config-file>`: clone repos in `config-file` to prescribed paths.\n- `gita context`: context sub-command\n - `gita context`: show current context\n - `gita context <group-name>`: set context to `group-name`, all operations then only apply to repos in this group\n - `gita context auto`: set context automatically according to the current working directory\n - `gita context none`: remove context\n- `gita color`: color sub-command\n - `gita color [ll]`: Show available colors and the current coloring scheme\n - `gita color reset`: Reset to the default coloring scheme\n - `gita color set <situation> <color>`: Use the specified color for the local-remote situation\n- `gita flags`: flags sub-command\n - `gita flags set <repo-name> <flags>`: add custom `flags` to repo\n - `gita flags [ll]`: display repos with custom flags\n- `gita freeze`: print information of all repos such as URL, name, and path. Use with\n `gita clone`.\n- `gita group`: group sub-command\n - `gita group add <repo-name(s)> -n <group-name>`: add repo(s) to a new or existing group\n - `gita group [ll]`: display existing groups with repos\n - `gita group ls`: display existing group names\n - `gita group rename <group-name> <new-name>`: change group name\n - `gita group rm <group-name(s)>`: delete group(s)\n - `gita group rmrepo <repo-name(s)> -n <group-name>`: remove repo(s) from existing group\n- `gita info`: info sub-command\n - `gita info [ll]`: display the used and unused information items\n - `gita info add <info-item>`: enable information item\n - `gita info rm <info-item>`: disable information item\n- `gita ll`: display the status of all repos\n- `gita ll <group-name>`: display the status of repos in a group\n- `gita ll -g`: display the repo summaries by groups\n- `gita ls`: display the names of all repos\n- `gita ls <repo-name>`: display the absolute path of one repo\n- `gita rename <repo-name> <new-name>`: rename a repo\n- `gita rm <repo-name(s)>`: remove repo(s) from `gita` (won't remove files on disk)\n- `gita -v`: display gita version\n\nThe `git` delegating sub-commands are of two formats\n\n- `gita <sub-command> [repo-name(s) or group-name(s)]`:\n optional repo or group input, and **no input means all repos**.\n- `gita <sub-command> <repo-name(s) or groups-name(s)>`:\n required repo name(s) or group name(s) input\n\nThey translate to `git <sub-command>` for the corresponding repos.\nBy default, only `fetch` and `pull` take optional input. In other words,\n`gita fetch` and `gita pull` apply to all repos.\nTo see the pre-defined sub-commands, run `gita -h` or take a look at\n[cmds.json](https://github.com/nosarthur/gita/blob/master/gita/cmds.json).\nTo add your own sub-commands or override the default behaviors, see the [customization section](#custom).\nTo run arbitrary `git` command, see the [superman mode section](#superman).\n\nIf more than one repos are specified, the `git` command runs asynchronously,\nwith the exception of `log`, `difftool` and `mergetool`,\nwhich require non-trivial user input.\n\nRepo configuration global is saved in `$XDG_CONFIG_HOME/gita/repos.csv`\n(most likely `~/.config/gita/repos.csv`) or if you prefered at project configuration add environment variable `GITA_PROJECT_HOME`.\n\n## Installation\n\nTo install the latest version, run\n\n```\npip3 install -U gita\n```\n\nIf you prefer development mode, download the source code and run\n\n```\npip3 install -e <gita-source-folder>\n```\n\nIn either case, calling `gita` in terminal may not work,\nthen put the following line in the `.bashrc` file.\n\n```\nalias gita=\"python3 -m gita\"\n```\n\nWindows users may need to enable the ANSI escape sequence in terminal for\nthe branch color to work.\nSee [this stackoverflow post](https://stackoverflow.com/questions/51680709/colored-text-output-in-powershell-console-using-ansi-vt100-codes) for details.\n\n## Auto-completion\n\nYou 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.\n\n### Bash\nDownload [.gita-completion.bash](https://github.com/nosarthur/gita/blob/master/.gita-completion.bash) and source it in shell.\n\n### Zsh\nThere are 2 options :\n- [.gita-completion.zsh](https://github.com/nosarthur/gita/blob/master/contrib.completion/zsh/.gita-completion.zsh). Use the help of gita command to display options. It uses the bash completion system for zsh.\nAdd `autoload -U +X bashcompinit && bashcompinit` in .zshrc and source the zsh file\n- [_gita](https://github.com/nosarthur/gita/blob/master/contrib.completion/zsh/_gita_).\nCompletion more Zsh style. Copy it in a folder and add this folder path in `FPATH` variable. This completion file doesn't take account to command from cmds.json\n\n### Fish\nDownload [gita.fish](https://github.com/nosarthur/gita/tree/master/auto-completion/fish/gita.fish) and place it in `~/.config/fish/completions/`\n\n\n## <a name='superman'></a> Superman mode\n\nThe superman mode delegates any `git` command or alias.\nUsage:\n\n```\ngita super [repo-name(s) or group-name(s)] <any-git-command-with-or-without-options>\n```\n\nHere `repo-name(s)` or `group-name(s)` are optional, and their absence means all repos.\nFor example,\n\n- `gita super checkout master` puts all repos on the master branch\n- `gita super frontend-repo backend-repo commit -am 'implement a new feature'`\n executes `git commit -am 'implement a new feature'` for `frontend-repo` and `backend-repo`\n\n## <a name='shell'></a> Shell mode\n\nThe shell mode delegates any shell command.\nUsage:\n\n```\ngita shell [repo-name(s) or group-name(s)] <any-shell-command>\n```\n\nHere `repo-name(s)` or `group-name(s)` are optional, and their absence means all repos.\nFor example,\n\n- `gita shell ll` lists contents for all repos\n- `gita shell repo1 repo2 mkdir docs` create a new directory `docs` in `repo1` and `repo2`\n- `gita shell \"git describe --abbrev=0 --tags | xargs git checkout\"`: check out the latest tag for all repos\n\n## <a name='custom'></a> Customization\n\n### define repo group and context\n\nWhen the project contains several independent but related repos,\nwe can define a group and execute `gita` command on this group.\nFor example,\n\n```\ngita group add repo1 repo2 -n my-group\ngita ll my-group\ngita pull my-group\n```\n\nTo save more typing, one can set a group as context, then any `gita` command\nis scoped to the group\n\n```\ngita context my-group\ngita ll\ngita pull\n```\n\nThe most useful context maybe `auto`.\nIn this mode, the context is automatically determined from the\ncurrent working directory (CWD): the context is the group whose member repo's\npath contains CWD. To set it, run\n\n```\ngita context auto\n```\n\nTo remove the context, run\n```\ngita context none\n```\n\nIt is also possible to recursively add repos within a directory and\ngenerate hierarchical groups automatically. For example, running\n\n```\ngita add -a src\n```\non the following folder structure\n```\nsrc\n\u251c\u2500\u2500 project1\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 repo1\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 repo2\n\u251c\u2500\u2500 repo3\n\u251c\u2500\u2500 project2\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 repo4\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 repo5\n\u2514\u2500\u2500 repo6\n```\ngives rise to 3 groups:\n```\nsrc:repo1,repo2,repo3,repo4,repo5,repo6\nsrc-project1:repo1,repo2\nsrc-project2:repo4,repo5\n```\n\n### add user-defined sub-command using json file\n\nCustom delegating sub-commands can be defined in `$XDG_CONFIG_HOME/gita/cmds.json`\n(most likely `~/.config/gita/cmds.json`)\nAnd they shadow the default ones if name collisions exist.\n\nDefault delegating sub-commands are defined in\n[cmds.json](https://github.com/nosarthur/gita/blob/master/gita/cmds.json).\nFor example, `gita stat <repo-name(s)>` is registered as\n\n```json\n\"stat\":{\n \"cmd\": \"git diff --stat\",\n \"help\": \"show edit statistics\"\n}\n```\n\nwhich executes `git diff --stat` for the specified repo(s).\n\nTo disable asynchronous execution, set `disable_async` to be `true`.\nSee the `difftool` example:\n\n```json\n\"difftool\":{\n \"cmd\": \"git difftool\",\n \"disable_async\": true,\n \"help\": \"show differences using a tool\"\n}\n```\n\nIf you want a custom command to behave like `gita fetch`, i.e., to apply to all\nrepos when no repo is specified, set `allow_all` to be `true`.\nFor example, the following snippet creates a new command\n`gita comaster [repo-name(s)]` with optional repo name input.\n\n```json\n\"comaster\":{\n \"cmd\": \"checkout master\",\n \"allow_all\": true,\n \"help\": \"checkout the master branch\"\n}\n```\n\nAny command that runs in the [superman mode](#superman) mode or the\n[shell mode](#shell) can be defined in this json format.\nFor example, the following command runs in shell mode and fetches only the\ncurrent branch from upstream.\n\n```json\n\"fetchcrt\":{\n \"cmd\": \"git rev-parse --abbrev-ref HEAD | xargs git fetch --prune upstream\",\n \"allow_all\": true,\n \"shell\": true,\n \"help\": \"fetch current branch only\"\n}\n```\n\n### customize the local/remote relationship coloring displayed by the `gita ll` command\n\nYou can see the default color scheme and the available colors via `gita color`.\nTo change the color coding, use `gita color set <situation> <color>`.\nThe configuration is saved in `$XDG_CONFIG_HOME/gita/color.csv`.\n\n### customize information displayed by the `gita ll` command\n\nYou can customize the information displayed by `gita ll`.\nThe used and unused information items are shown with `gita info`, and the\nconfiguration is saved in `$XDG_CONFIG_HOME/gita/info.csv`.\n\nFor example, the default setting corresponds to\n\n```csv\nbranch,commit_msg,commit_time\n```\n\nHere `branch` includes both branch name and status.\nThe status symbols are similar to the ones used in [spaceship-prompt](https://spaceship-prompt.sh/sections/git/#Git-status-git_status).\n\nTo customize these symbols, add a file in `$XDG_CONFIG_HOME/gita/symbols.csv`.\nThe default settings corresponds to\n\n```csv\ndirty,staged,untracked,local_ahead,remote_ahead,diverged,in_sync,no_remote\n*,+,?,\u2191,\u2193,\u21d5,,\u2205\n```\nOnly the symbols to be overridden need to be defined.\nYou can search unicode symbols [here](https://www.compart.com/en/unicode/).\n\n### customize git command flags\n\nOne can set custom flags to run `git` commands. For example, with\n\n```\ngita flags set my-repo --git-dir=`gita ls dotfiles` --work-tree=$HOME\n```\n\nany `git` command/alias triggered from `gita` on `dotfiles` will use these flags.\nNote that the flags are applied immediately after `git`. For example,\n`gita st dotfiles` translates to\n\n```\ngit --git-dir=$HOME/somefolder --work-tree=$HOME status\n```\n\nrunning from the `dotfiles` directory.\n\nThis feature was originally added to deal with\n[bare repo dotfiles](https://www.atlassian.com/git/tutorials/dotfiles).\n\n## Requirements\n\nGita requires Python 3.6 or higher, due to the use of\n[f-string](https://www.python.org/dev/peps/pep-0498/)\nand [asyncio module](https://docs.python.org/3.6/library/asyncio.html).\n\nUnder the hood, gita uses `subprocess` to run git commands/aliases.\nThus the installed git version may matter.\nI have git `1.8.3.1`, `2.17.2`, and `2.20.1` on my machines, and\ntheir results agree.\n\n## Tips\n\n| effect | shell command |\n| ------------------------- | ---------------------------------------- |\n| enter `<repo>` directory | `` cd `gita ls <repo>` `` |\n| delete repos in `<group>` | `gita group ll <group> \\| xargs gita rm` |\n\n## Contributing\n\nTo contribute, you can\n\n- report/fix bugs\n- request/implement features\n- star/recommend this project\n\nRead [this article](https://www.dataschool.io/how-to-contribute-on-github/) if you have never contribute code to open source project before.\n\nChat room is available on [](https://gitter.im/nosarthur/gita?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)\n\nTo run tests locally, simply `pytest` in the source code folder.\nNote that context should be set as `none`.\nMore implementation details are in\n[design.md](https://github.com/nosarthur/gita/blob/master/doc/design.md).\nA step-by-step guide to reproduce this project is [here](https://nosarthur.github.io/side%20project/2019/05/27/gita-breakdown.html).\n\nYou can also sponsor me on [GitHub](https://github.com/sponsors/nosarthur). Any amount is appreciated!\n\n## Other multi-repo tools\n\nI haven't tried them but I heard good things about them.\n\n- [myrepos](https://myrepos.branchable.com/)\n- [repo](https://source.android.com/setup/develop/repo)\n- [mu-repo](https://github.com/fabioz/mu-repo)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Manage multiple git repos with sanity",
"version": "0.16.7.1",
"project_urls": {
"Homepage": "https://github.com/nosarthur/gita"
},
"split_keywords": [
"git",
" manage multiple repositories",
" cui",
" command-line"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1018fe4eba560324f51df64d969f2e0fc93f1bb63ee67991b8eff598843b3777",
"md5": "ed0fe6bb09c7a114d1b1bb81e7f7ec45",
"sha256": "c489a04d178be52e48860373b0bb628af98d29a58ce1bf6b6c623f741f2fdc25"
},
"downloads": -1,
"filename": "gita-0.16.7.1.tar.gz",
"has_sig": false,
"md5_digest": "ed0fe6bb09c7a114d1b1bb81e7f7ec45",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.6",
"size": 34391,
"upload_time": "2024-06-04T01:57:25",
"upload_time_iso_8601": "2024-06-04T01:57:25.235713Z",
"url": "https://files.pythonhosted.org/packages/10/18/fe4eba560324f51df64d969f2e0fc93f1bb63ee67991b8eff598843b3777/gita-0.16.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-04 01:57:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nosarthur",
"github_project": "gita",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "gita"
}
JSON
