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
|
Powerline Gitstatus
===================
A [Powerline][1] segment for showing the status of a Git working copy.
By [Jasper N. Brouwer][2].
It will show the branch-name, or the commit hash if in detached head state.
It will also show the number of commits behind, commits ahead, staged files,
unmerged files (conflicts), changed files, untracked files and stashed files
if that number is greater than zero.
![screenshot][4]
Glossary
--------
- ``: branch name or commit hash
- `★`: most recent tag (if enabled)
- `↓`: n commits behind
- `↑`: n commits ahead
- `●`: n staged files
- `✖`: n unmerged files (conflicts)
- `✚`: n changed files
- `…`: n untracked files
- `⚑`: n stashed files
Requirements
------------
The Gitstatus segment requires [git][5]! Preferably, but not limited to, version 1.8.5 or higher.
Version 1.8.5 will enable the usage of the `-C` parameter, which is more performant and accurate.
Installation
------------
### On Debian/Ubuntu
On a recent enough Debian (at least Stretch with backports enabled) or Ubuntu (at least 18.10) there is an official package available.
```txt
apt install powerline-gitstatus
```
This command will also instruct your package manager to install Powerline, if it's not already available.
Powerline will be automatically configured to use the Gitstatus highlight groups and add the segment to the default
shell theme.
### Using pip
```txt
pip install powerline-gitstatus
```
Configuration
-------------
The Gitstatus segment uses a couple of custom highlight groups. You'll need to define those groups in your colorscheme,
for example in `.config/powerline/colorschemes/default.json`:
```json
{
"groups": {
"gitstatus": { "fg": "gray8", "bg": "gray2", "attrs": [] },
"gitstatus_branch": { "fg": "gray8", "bg": "gray2", "attrs": [] },
"gitstatus_branch_clean": { "fg": "green", "bg": "gray2", "attrs": [] },
"gitstatus_branch_dirty": { "fg": "gray8", "bg": "gray2", "attrs": [] },
"gitstatus_branch_detached": { "fg": "mediumpurple", "bg": "gray2", "attrs": [] },
"gitstatus_tag": { "fg": "darkcyan", "bg": "gray2", "attrs": [] },
"gitstatus_behind": { "fg": "gray10", "bg": "gray2", "attrs": [] },
"gitstatus_ahead": { "fg": "gray10", "bg": "gray2", "attrs": [] },
"gitstatus_staged": { "fg": "green", "bg": "gray2", "attrs": [] },
"gitstatus_unmerged": { "fg": "brightred", "bg": "gray2", "attrs": [] },
"gitstatus_changed": { "fg": "mediumorange", "bg": "gray2", "attrs": [] },
"gitstatus_untracked": { "fg": "brightestorange", "bg": "gray2", "attrs": [] },
"gitstatus_stashed": { "fg": "darkblue", "bg": "gray2", "attrs": [] },
"gitstatus:divider": { "fg": "gray8", "bg": "gray2", "attrs": [] }
}
}
```
Then you can activate the Gitstatus segment by adding it to your segment configuration,
for example in `.config/powerline/themes/shell/default.json`:
```json
{
"function": "powerline_gitstatus.gitstatus",
"priority": 40
}
```
The Gitstatus segment will use the `-C` argument by default, but this requires git 1.8.5 or higher.
If you cannot meet that requirement, you'll have to disable the usage of `-C`.
Do this by passing `false` to the `use_dash_c` argument, for example in `.config/powerline/themes/shell/__main__.json`:
```json
"gitstatus": {
"args": {
"use_dash_c": false
}
}
```
Optionally, a tag description for the current branch may be displayed using the `show_tag` option. Valid values for this
argument are:
* `last` : shows the most recent tag
* `annotated` : shows the most recent annotated tag
* `contains` : shows the closest tag that comes after the current commit
* `exact` : shows a tag only if it matches the current commit
You can enable this by passing one of these to the `show_tag` argument, for example in `.config/powerline/themes/shell/__main__.json`:
```json
"gitstatus": {
"args": {
"show_tag": "exact"
}
}
```
Git is executed an additional time to find this tag, so it is disabled by default.
Note: before v1.3.0, the behavior when the value is `True` was `last`. As of v1.3.0 onwards, `True` behaves as `exact`.
Optionally the format in which Gitstatus shows information can be customized.
This allows to use a different symbol or remove a fragment if desired. You can
customize string formats for _branch_, _tag_, _behind_, _ahead_, _staged_, _unmerged_,
_changed_, _untracked_ and _stash_ fragments with the following arguments in a
theme configuration file, for example `.config/powerline/themes/shell/__main__.json`:
```json
"gitstatus": {
"args": {
"formats": {
"branch": "\ue0a0 {}",
"tag": " ★ {}",
"behind": " ↓ {}",
"ahead": " ↑ {}",
"staged": " ● {}",
"unmerged": " ✖ {}",
"changed": " ✚ {}",
"untracked": " … {}",
"stashed": " ⚑ {}"
}
}
}
```
By default, when in detached head state (current revision is not a branch tip), Gitstatus shows a short commit hash in
place of the branch name. This can be replaced with a description of the closest reachable ref using the
`detached_head_style` argument, for example in `.config/powerline/themes/shell/__main__.json`:
```json
"gitstatus": {
"args": {
"detached_head_style": "ref"
}
}
```
By default, if your local branch has untracked files but no other changes, the branch status will be highlighted as dirty in the segment. You can disable this behavior by setting the `untracked_not_dirty` argument to `true`, for example in `.config/powerline/themes/shell/__main__.json`:
```json
"gitstatus": {
"args": {
"untracked_not_dirty": true
}
}
```
License
-------
Licensed under [the MIT License][3].
[1]: https://powerline.readthedocs.org/en/master/
[2]: https://github.com/jaspernbrouwer
[3]: https://github.com/jaspernbrouwer/powerline-gitstatus/blob/master/LICENSE
[4]: https://github.com/jaspernbrouwer/powerline-gitstatus/blob/master/screenshot.png
[5]: https://git-scm.com/
|
