An interactive, keyboard driven git viewer based on urwid. Similar to gitk but in a terminal.
Project description
A simple keyboard driven git log viewer. Similar to gitk but in a terminal based on urwid.
The log view showing the history of commits (left) and a details view showing more information for the selected commit incl diff with line numbers and a list of other commits referencing this commit (right)
A details view showing link hints after pressing f, pressing the key indicated in the square brackets with blue background will open that git object.
Line numbers are not available if --word-diff
is used which can be toggled with W
.
The list of keyboard shortcuts can be opened by pressing F2
or s
.
It adapts automatically if you (re)map keys in your config file.
Advantages over gitk
:
- same window
- no problems with resizing window
- window does not need to be as big
- keyboard navigation
- shows untracked files
- shows stashes
- line numbers in front of changed lines
- shows commits which mention the current commit in their commit message
- no separate configuration of colors
- more configurable (keyboard shortcuts, change the commands which produce the output)
- you can directly open the current file at the current line in an editor
Advantages over git log
/git diff
:
- interactively select a commit and look into it without needing to copy and paste a hash
- hash ids are recognized as links which you can follow
- separators between different files in diff for a better overview
- easy copy of different information via keyboard
- line numbers in front of changed lines
Implemented features:
- display git log
- select a commit
- open a commit (display details including a diff)
- show referencing commits
- open an annotated tag
- open a file (display it's entire contents at a certain commit)
- hash ids are recognized as links which you can follow
- yank different information (
yy
for hash,yt
for title,yc
for committer, ...) - display unstaged changes and index
- display stashed changes
- show line numbers in front of changed lines referring to the version after the change
- switch to line numbers referring to the version before the change with
X
- jump to commit with
"
- search with
/
(forward) or?
(backward) - passing through command line arguments to git
- show unreachable commits with
gitl --unreachable
(in case you accidentally dropped a still needed stash, see also git stash --help/Recovering stash entries) - enable or disable line breaks with the settings app.wrap and details-view.wrap
Control+o
/Control+i
jump to previously/next selected line- jump to next file in details view with
]]
and to previous with[[
- jump to next hunk in details view with
}
and to previous with{
- side by side view of log and details (enable with
e
and disable withw
) - open the file in the working directory with
o
- open the file as it was after the current commit with
i
- open the file as it was before the current commit with
U
/I
(left/right version in case of a merge) - reload with
F5
- config with
p
- help with
F1
- list of all keyboard short cuts with
F2
(changes automatically if you rebind keys) - help for all commands which can be used in config files or that keys can be bound (
F3
) - help for all settings (
F4
) - help for command line options with
gitl --help
,gitd --help
andgits --help
Ideas for future versions:
- open commit in ranger
- bash auto completion
- list of tags (for the time being:
gitl --no-walk --tags
) - list of changed/added/deleted files (expand/collapse diff)
- command line
- show content of new files
- mark a line with mx, jump to it with 'x or `x (In this program there is no difference between a backtick and a single quote because there is only linewise motion.)
- jump to next merge with
{ and jump to last split with
} - star/hash: search for current title
- set terminal title
Known bugs:
- depending on the color settings of your terminal colored text has a different background color. Monokai and Gruvbox_light do not have this problem.
- with some terminals (e.g. kitty and alacritty) when decreasing the window width and thus causing lines containing full width characters to break duplicates of the full width characters appear in the first column of the indentation.
When increasing the window width again those duplicates disappear.
You can avoid this with
--explicit-spaces
(if your urwid version is new enough), by disabling the indentation using--align left
possibly in combination with--wrap clip
(or--wrap ellipsis
if your urwid version is new enough) or using another terminal (e.g. termite or sakura). - urwid crashes if you reduce the window width down to two screen columns and use full width characters and the log history is longer than your screen, see https://github.com/urwid/urwid/issues/468
Known issues with outdated urwid versions:
- urwid 2.0.1:
--wrap ellipsis
and--explicit-spaces
are not supported - urwid 1.3.1: search does not work well (selected line is sometimes not updated)
Installation
Development install
If you want to tinker with the code:
$ git clone https://gitlab.com/erzo/gitu.git git-viewer
$ pip install -r git-viewer/requirements.txt
$ pip install -e git-viewer
Manual install
This program requires Python 3.5 or newer and is not compatible with Python 2.
It depends on the nonstandard library urwid for the user interface which can be installed with pip3 install --user urwid
or via the system package manager.
This program is a wrapper around git therefore git needs to be installed.
Most features work with urwid 1.3.1 but not all of them, see the list of Known issues with outdated urwid versions above. I recommend using a newer version.
Since this program is installable via pip it is not possible to execute it directly.
Instead the code must be placed somewhere where python finds it as a package and then you can run it with python -m git_viewer
.
Installing dependencies on Arch
$ sudo pacman -Syu
$ sudo pacman -S python python-urwid git
Installing dependencies on Debian
$ sudo apt install python3
$ sudo apt install python3-urwid
$ sudo apt install git
Installing this program
Run the following commands from the directory where you want to keep the git repository. Keeping the git repository is important so you can easily do updates.
$ git clone 'https://gitlab.com/erzo/gitu.git' git-viewer
$ # if several versions of python3 are installed be careful to replace the * with the correct version
$ ln -s "$(realpath git-viewer/src/git_viewer)" ~/.local/lib/python3*/site-packages/
$ echo 'python -m git_viewer "$@"' > ~/.local/bin/gitl
$ echo 'python -m git_viewer.diff "$@"' > ~/.local/bin/gitd
$ echo 'python -m git_viewer.show "$@"' > ~/.local/bin/gits
$ chmod a+x ~/.local/bin/git[lds]
If ln
or echo
fail with No such file or directory
create the necessary directories with mkdir -p <path>
and repeat the command.
Make sure ~/.local/bin is contained in your PATH variable.
(You can check this using echo "$PATH"
.)
If it is not, add it:
$ echo 'export PATH="$PATH:$HOME/.local/bin"' >>~/.profile
If ~/.profile is not loaded automatically, load it from .xsessionrc or however that config file is called on your system:
$ echo '[ -f ~/.profile ] && . ~/.profile' >>~/.xsessionrc
Optional dependencies
wl-copy
(on Wayland) orxclip
(on X) for copying to the clipboard- the python library
packaging
for checking the version of the urwid library, you don't need this if you are using urwid 2.1.0 or newer but with older urwid versions unsupported options can otherwise lead to unexpected crashes - one of the python libraries
appdirs
,xdgappdirs
orplatformdirs
in order to look for config files. Without these libraries "$XDG_CONFIG_HOME/git-viewer/config" and "~/.config/git-viewer/config" are tried.
Updates
Change directory to the git repository and run git pull
.
Usage
See gitl --help
for the supported command line arguments.
Run gitl and
- press
F1
orx
for an introduction how to use git-viewer - press
F2
ors
for a list of all keyboard shortcuts - press
F3
orc
for a list of all commands which can be mapped to keys and used in config files - press
F4
ord
for a list of all settings
A raw version of the introduction (without the automatically added keyboard shortcuts for the corresponding commands) can be displayed here.
gitd
gitl comes with two little side programs which I am calling gitd and gits.
gitd is a wrapper around git diff
using gitl's details view.
You can use it for example to:
- show unstaged changes
gitd
- show staged changes
gitd --cached
- compare two branches
gitd master origin/otherbranch
For more information see git diff --help
.
gits
gits is a wrapper around git show
using gitl's details view.
You can use it for example in your vimrc to open the commit under the cursor, see vim integration.
For more information see git show --help
.
vim integration
Putting the following line in your vimrc will show the commit under the cursor when pressing Ctrl+C (one of the few keyboard shortcuts which is not defined by default). This is useful when writing commit messages or doing an interactive rebase.
map <c-c> :!gits <c-r><c-w><cr><cr>
Open the commit in a new window (using kitty):
map <c-c> :call OpenCommitInNewWindow()<cr>
let b:cmdpipe = ""
function! OpenCommitInNewWindow() abort
if ! filereadable(b:cmdpipe)
echo "no pipe"
let b:cmdpipe = substitute(system('mktemp -u'), '\n\+$', '', '')
call system("mkfifo '" . b:cmdpipe . "'")
execute "silent ! kitty gits --command-pipe '" . b:cmdpipe . "' &"
endif
execute "silent !echo 'select " . expand('<cword>') . "' >>'" . b:cmdpipe . "'"
redraw!
endfunction
(The --command-pipe
option uses polling to check if something has been read from the pipe. The polling time can be adjusted with set app.command-pipe-poll-time=<time-in-seconds>
.)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for git_viewer-0.15.2.dev0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e48e8332e0fdf549a73725e7fbb86bb153177231fb2827ae4a3025231f818574 |
|
MD5 | 6a01cce3d19fc7006a6a863d16ce8204 |
|
BLAKE2b-256 | dd21280b43b4b7f62296674c878a57b810e9d421f311fe286ef91d532cc6d003 |