1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
[](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.10
```
# Gita: a command-line tool to manage multiple git repos
This tool does two things
- display the status of multiple git repos such as branch, modification, commit message side by side
- (batch) delegate git commands/aliases from any working directory
If several repos are related, it helps to see their status together too.
I also hate to change directories to execute git commands.
Here the branch color distinguishes 5 situations between local and remote branches:
- 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.
The additional status symbols denote
- `+`: staged changes
- `*`: unstaged changes
- `_`: untracked files/folders
The bookkeeping sub-commands are
- `gita add <repo-path(s)>`: add repo(s) to `gita`
- `gita rm <repo-name(s)>`: remove repo(s) from `gita` (won't remove files from disk)
- `gita group`: show grouping of the repos
- `gita group <repo-name(s)>`: group repos
- `gita ungroup <repo-name(s)>`: remove grouping for repos
- `gita ll`: display the status of all repos
- `gita ll <group-name>`: display the status of repos in a group
- `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 info`: display the used and unused information items
- `gita -v`: display gita version
Repo paths are saved in `$XDG_CONFIG_HOME/gita/repo_path` (most likely `~/.config/gita/repo_path`).
The 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
By default, only `fetch` and `pull` take optional input.
If more than one repos are specified, the git command will run asynchronously,
with the exception of `log`, `difftool` and `mergetool`, which require non-trivial user input.
## Installation
To install the latest version, run
```
pip3 install -U gita
```
If development mode is preferred,
download the source code and run
```
pip3 install -e <gita-source-folder>
```
In either case, calling `gita` in terminal may not work,
then you can 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, otherwise
the branch color won't work.
See [this stackoverflow post](https://stackoverflow.com/questions/51680709/colored-text-output-in-powershell-console-using-ansi-vt100-codes) for details.
## Auto-completion
Download
[.gita-completion.bash](https://github.com/nosarthur/gita/blob/master/.gita-completion.bash)
or
[.gita-completion.zsh](https://github.com/nosarthur/gita/blob/master/.gita-completion.zsh)
and source it in the .rc file.
## Superman mode
The superman mode delegates any git command/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`
## Customization
Custom delegating sub-commands can be defined in `$XDG_CONFIG_HOME/gita/cmds.yml`
(most likely `~/.config/gita/cmds.yml`).
And they shadow the default ones if name collisions exist.
Default delegating sub-commands are defined in
[cmds.yml](https://github.com/nosarthur/gita/blob/master/gita/cmds.yml).
For example, `gita stat <repo-name(s)>` is registered as
```yaml
stat:
cmd: diff --stat
help: show edit statistics
```
which executes `git diff --stat`.
If the delegated git command is a single word, the `cmd` tag can be omitted.
See `push` for an example.
To disable asynchronous execution, set the `disable_async` tag to be `true`.
See `difftool` for an example.
If you want a custom command to behave like `gita fetch`, i.e., to apply
command to all repos if nothing is specified,
set the `allow_all` option to be `true`.
For example, the following snippet creates a new command
`gita comaster [repo-name(s)]` with optional repo name input.
```yaml
comaster:
cmd: checkout master
allow_all: true
help: checkout the master branch
```
Another customization is the information items displayed by `gita ll`.
The used and unused information items are shown with `gita info` and one can
create `$XDG_CONFIG_HOME/gita/info.yml` to customize it. For example, the
default information items setting corresponds to
```yaml
- branch
- commit_msg
```
To create your own information items, define a dictionary called `extra_info_items`
in `$XDG_CONFIG_HOME/gita/extra_repo_info.py`. It should map strings to functions,
where the strings are the information item names and the functions take repo path
as input. A trivial example is shown below.
```python
def get_delim(path: str) -> str:
return '|'
extra_info_items = {'delim': get_delim}
```
If it works, you will see these extra items in the 'Unused' section of the
`gita info` output. To use them, edit `$XDG_CONFIG_HOME/gita/extra_repo_info.py`.
## 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.
## Contributing
To contribute, you can
- report/fix bugs
- request/implement features
- star/recommend this project
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`.
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!
## Contributors
[](https://github.com/nosarthur)
[](https://github.com/mc0239)
[](https://github.com/dgrant)
[](https://github.com/samibh)
[](https://github.com/wbrn)
[](https://github.com/TpOut)
[](https://github.com/PabloCastellano)
[](https://github.com/cd3)
[](https://github.com/Steve-Xyh)
## 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)
|
