• Stars
    star
    549
  • Rank 79,432 (Top 2 %)
  • Language
    Go
  • License
    MIT License
  • Created over 4 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

πŸ’» Git in your tmux status bar

Gitmux shows git status in your tmux status bar


tests goreport

demo

  • easy. Install and forget about it
  • minimal. Just shows what you need, when you need it
  • discrete. Get out of your way if current directory is not in a Git tree
  • shell-agnostic. Does not rely on shell-features so works with all of them
  • customizable. Colors, symbols and layout are configurable

Prerequisites

Works with all reasonably recent tmux versions (2.1+)

Installing

Binary release

Download the latest binary for your platform/architecture and uncompress it.

Homebrew tap (macOS and linux) (amd64 and arm64)

Install the latest version with:

brew tap arl/arl
brew install gitmux

AUR

Arch Linux users can download the gitmux, gitmux-bin or gitmux-git AUR package.

From source

Download and install a Go compiler (Go 1.16 or later). Run go install to build and install gitmux:

go install github.com/arl/gitmux@latest

Getting started

If your tmux version supports pane_current_path (tmux v2.1+), just add this line to your .tmux.conf:

set -g status-right '#(gitmux "#{pane_current_path}")'

If your tmux doesn't support pane_current_path then you can use a bash-specific solution to achieve relatively similar behaviour: gitmux will refresh after every shell command you run or when you switch windows, however it won't refresh automatically, nor when switching panes.

Note that tmux v2.1 was released in 2015 so you're probably better off updating to a more recent version anyway πŸ™‚.

Customizing

gitmux output can be customized via a configuration file in YAML format.

This is the default gitmux configuration file, in YAML format:

tmux:
    symbols:
        branch: 'βŽ‡ '
        hashprefix: ':'
        ahead: ↑·
        behind: ↓·
        staged: '● '
        conflict: 'βœ– '
        modified: '✚ '
        untracked: '… '
        stashed: 'βš‘ '
        clean: βœ”
        insertions: Ξ£
        deletions: Ξ”
    styles:
        clear: '#[fg=default]'
        state: '#[fg=red,bold]'
        branch: '#[fg=white,bold]'
        remote: '#[fg=cyan]'
        divergence: '#[fg=default]'
        staged: '#[fg=green,bold]'
        conflict: '#[fg=red,bold]'
        modified: '#[fg=red,bold]'
        untracked: '#[fg=magenta,bold]'
        stashed: '#[fg=cyan,bold]'
        clean: '#[fg=green,bold]'
        insertions: '#[fg=green]'
        deletions: '#[fg=red]'
    layout: [branch, .., remote-branch, divergence, '- ', flags]
    options:
        branch_max_len: 0
        branch_trim: right
        ellipsis: …
        hide_clean: false
        swap_divergence: false

First, save the default configuration to a new file:

gitmux -printcfg > $HOME/.gitmux.conf

Modify the line you've added to .tmux.conf, passing the path of the configuration file as argument to gitmux via the -cfg flag

set -g status-right '#(gitmux -cfg $HOME/.gitmux.conf "#{pane_current_path}")'

Open .gitmux.conf and modify it, replacing symbols, styles and layout to suit your needs.

In tmux status bar, gitmux output immediately reflects the changes you make to the configuration.

gitmux configuration is split into 4 sections:

  • symbols: they're just strings of unicode characters
  • styles: tmux format strings
  • layout: list of gitmux layout components, defines the component to show and in their order.
  • options: additional configuration options

Symbols

The symbols section defines the symbols printed before specific elements of Git status displayed in tmux status string:

  symbols:
        branch: "βŽ‡ "    # current branch name.
        hashprefix: ":"  # Git SHA1 hash (in 'detached' state).
        ahead: ↑·        # 'ahead count' when local and remote branch diverged.
        behind: ↓·       # 'behind count' when local and remote branch diverged.
        staged: "● "     # count of files in the staging area.
        conflict: "βœ– "   # count of files in conflicts.
        modified: "✚ "   # count of modified files.
        untracked: "… "  # count of untracked files.
        stashed: "βš‘ "    # count of stash entries.
        insertions: Ξ£    # count of inserted lines (stats section).
        deletions: Ξ”     # count of deleted lines (stats section).
        clean: βœ”         # Shown when the working tree is clean.

Styles

Styles are tmux format strings used to specify text colors and attributes of Git status elements. See the STYLES section of tmux man page.

  styles:
    clear: '#[fg=default]'          # Clear previous style.
    state: '#[fg=red,bold]'         # Special tree state strings such as [rebase], [merge], etc.
    branch: '#[fg=white,bold]'      # Local branch name
    remote: '#[fg=cyan]'            # Remote branch name
    divergence: "#[fg=yellow]"      # 'divergence' counts
    staged: '#[fg=green,bold]'      # 'staged' count
    conflict: '#[fg=red,bold]'      # 'conflicts' count
    modified: '#[fg=red,bold]'      # 'modified' count
    untracked: '#[fg=magenta,bold]' # 'untracked' count
    stashed: '#[fg=cyan,bold]'      # 'stash' count
    insertions: '#[fg=green]'       # 'insertions' count
    deletions: '#[fg=red]'          # 'deletions' count
    clean: '#[fg=green,bold]'       # 'clean' symbol

Layout components

The layout section defines what components gitmux shows and the order in which they appear on tmux status bar.

For example, the default gitmux layout shows is:

layout: [branch, .., remote-branch, divergence, " - ", flags]

It shows, in that order:

  • the local branch name,
  • 2 dots characters ..,
  • the remote branch name
  • the local/remote divergence
  • a - character
  • and finally the flags representing the working tree state

Note that elements only appear when they make sense, for example if local and remote branch are aligned, the divergence string won't show up. Same thing for the remote branch, etc.

But you can anyway choose to never show some components if you wish, or to present them in a different order.

This is the list of the possible keywords for layout:

Layout keywords Description Example
branch local branch name main
remote-branch remote branch name origin/main
divergence divergence local/remote branch, if any ↓·2↑·1
remote alias for remote-branch followed by divergence origin/main ↓·2↑·1
flags Symbols representing the working tree state ✚ 1 βš‘ 1 … 2
stats Insertions/deletions (lines). Disabled by default Ξ£56 Ξ”21
any string foo Non-keywords are shown as-is hello gitmux

Some example layouts:

  • default layout:
layout: [branch, .., remote-branch, divergence, " - ", flags]
  • some examples layouts:
layout: [branch, divergence, " - ", flags]
layout: [flags, " ", branch]
layout: [branch, "|", flags, "|", stats]

Additional options

This is the list of additional configuration options:

Option Description Default
branch_max_len Maximum displayed length for local and remote branch names 0 (no limit)
branch_trim Trim left or right end of the branch (right or left) right (trailing)
ellipsis Character to show branch name has been truncated …
hide_clean Hides the clean flag entirely false
swap_divergence Swaps order of behind & ahead upstream counts false

Troubleshooting

Check the opened and closed issues and don't hesitate to report anything by filing a new one.

Gitmux takes too long to refresh?

In case gitmux takes too long to refresh, try to decrease the value of the status-interval option. A reasonable value is 2 seconds, which you can set in .tmux.conf with:

set -g status-interval 2

Check out tmux man page for more details.

Contributing

Pull requests are welcome.
For major changes, please open an issue first to open a discussion.

License: MIT

More Repositories

1

statsviz

πŸš€ Visualise your Go program runtime metrics in real time in the browser
Go
3,128
star
2

tmux-gitbar

Git in your tmux status bar
Shell
171
star
3

go-rquad

πŸ“Œ State of the art point location and neighbour finding algorithms for region quadtrees, in Go
Go
131
star
4

go-detour

πŸ‘Ύ Navigation mesh pathfinding and spatial reasoning library
Go
123
star
5

macdeployqtfix

To bundle a Qt application on Mac OSX, there is macdeployqt. To finish the job there is macdeployqtfix! βœ…
Python
60
star
6

golq

πŸ“‘ 2D locality queries in Go
Go
31
star
7

assertgo

Conditionally compiled assertions in Go
Go
18
star
8

scripts

this is my collection of bash scripts for everyday use
Shell
15
star
9

dotfiles

My dotfiles config... Feel free to use
Shell
8
star
10

udpnet

Game networking library in Go, based on UDP
Go
6
star
11

gogeo

Geometry library in Go
Go
5
star
12

gitstatus

Retrieve the Git status of a working tree, in Go.
Go
5
star
13

bitfield

Go-generate code to emulate C bit fields
Go
5
star
14

gioexp

Experiments with Gio, the cross-platform gui for Go
Go
3
star
15

evolve

Evolutionary Computation Framework
Go
3
star
16

fastlfu

LFU cache with O(1) runtime complexity for all operations: insertion, access and deletion (eviction). In Go.
Go
3
star
17

imgtools

Utilities for working with images in Go, completing the standard image package.
Go
3
star
18

gotypes

Automatically generate Go code from Go structures
Go
2
star
19

urlserv

URL shortener demo for First Steps with Go training
Go
2
star
20

iolib2

Output device abstraction. Mask device differences (serial port, LPT, file, ethernet, etc.). Extendable
Go
2
star
21

serve

Serves the content of a directory as HTTP.
Go
2
star
22

zsort

Useful additions to the sort package
Go
1
star
23

gencli

Go-generate your urfave/cli flags from a structure
Go
1
star
24

go-gencon

Go Generic Containers - Reduce boilerplate by generating containers for your datastructures
Go
1
star
25

gsettings-upd

A systemd service that updates gsettings values
Go
1
star
26

get-up-and-go

Solutions for exercices of the Tour of Go
Go
1
star
27

training

Firs steps with go (Go introduction training)
Go
1
star
28

bitstring

Go Bitstring module
Go
1
star
29

artificial

Artificial art framework and experiement
Go
1
star
30

beggining-with-go

Go
1
star
31

monitoring

Monitoring workshop source code
Go
1
star
32

math32

32 bits wrapper around the standard go math package
Go
1
star
33

opencog-workbench

A tool to assist in the control and visualization of the OpenCog AtomSpace. It should facilitate the comprehension of AGI dynamics and allow a researcher to guide, tune, and understand the various mind processes in action, handle the parsing of log files and dynamic configuration of a running OpenCog instance. (developed with Angular, Bootstrap)
JavaScript
1
star