Skip to content

Latest commit

 

History

History
184 lines (131 loc) · 6.68 KB

README.md

File metadata and controls

184 lines (131 loc) · 6.68 KB
Raw

Gex

crates.io download license stargazers

NOTE: GEX IS UNFINISHED SOFTWARE. As a result, many features are missing, and the interface can change at any moment.

Gex

Git workflow improvement CLI tool inspired by Magit. This project is still under initial development, but I am actively dogfooding it and features should be added relatively quickly.

Aims

Primarily, this is a personal project since I recently switched to Neovim from Emacs and miss the simplicity and efficiency of using Magit. However, I do have some general aims, which are subject to change:

  • Simple - uncluttered UI.
  • Intuitive - it should be easy to learn to use gex.
  • Cross platform - primary focus on Linux, but should work well on Windows and MacOS.
  • Configurable - certain preferences in gex should be configurable to suit your own workflow.
  • Comprehensive* - you should be able to use gex to do everything you can do in git.

* gex supports executing arbitrary git commands with : for when something is not yet available

Non-Aims

  • Magit port

While it serves as a major inspiration, I am not trying to 1:1 port the behaviour and functionality of Magit.

Installation

Crates.io

crates.io

NOTE: You will need Rust on your system for this installation method.

$ cargo install gex

Other

Gex packages are also maintained by the community in a handful of repositories.

Packaging status

Usage

To enter gex simply type gex in console, optionally providing a path.

$ gex

Full usage:

$ gex --help

Git workflow improvement CLI tool inspired by Magit

Usage: gex [OPTIONS] [PATH]

Arguments:
  [PATH]  The path to the repository [default: .]

Options:
  -c, --config-file <PATH>  Path to a config file to use
  -h, --help                Print help
  -V, --version             Print version

Navigation

Key Action
j / Down Move down
k / Up Move up
J Jump to next file
K Jump to previous file
Tab / Space Toggle expand
g Go to top
G Go to bottom

Gex actions

Key Action
s stage item
S stage all items
u unstage item
U unstage all items
e edit file/hunk
F pull from remote
: execute git command
! execute subprocess
r refresh
Esc cancel current
q quit gex

Gex commands

Key Action
c commit
b branch
p push
z stash

Configuration

Gex will look for a config file in the following places:

OS Path
Linux $XDG_CONFIG_HOME/gex/config.toml
MacOS $HOME/Library/Application Support/gex/config.toml
Windows {FOLDERID_RoamingAppData}/gex/config.toml

Here is an example config.toml:

[options]
auto_expand_files = false
auto_expand_hunks = true
editor = "nvim" # defaults to git's core.editor or $EDITOR or "vi"
lookahead_lines = 5
sort_branches = "-committerdate" # key to pass to `git branch --sort`. https://git-scm.com/docs/git-for-each-ref#_field_names
truncate_lines = true # `false` is not recommended - see #37
ws_error_highlight = "new" # override git's diff.wsErrorHighlight

# Named colours use the terminal colour scheme. You can also describe your colours
# by hex string "#RRGGBB", RGB "rgb_(r,g,b)" or by Ansi "ansi_(value)".
#
# This example uses a Gruvbox colour theme.
[colors]
foreground = "#ebdbb2"
background = "#282828"
heading = "#fabd2f"
hunk_head = "#d3869b"
addition = "#b8bb26"
deletion = "#fb4934"
key = "#d79921"
error = "#cc241d"

[keymap.navigation]
move_down     = ['j', "Down"]
move_up       = ['k', "Up"]
next_file     = ['J']
previous_file = ['K']
toggle_expand = [" ", "Tab"]
goto_top      = ['g']
goto_bottom   = ['G']

Versioning

A 0.X version increase indicates some change that could reasonably break someone's workflow. This is quite hard to define, so apologies if it does not meet your expectations. Usually this means changing a default setting or redesigning parts of the UI.

A 0.x.Y version increase indicates a change that should not break any workflow - i.e. fixing a bugs or adding features.

Whichever number is increased does not deliberately correlate with the size of the update.

1.0.0 will come when I consider the software to be "finished", subject to small improvements/features or bug fixes. What this means is very subjective, and my own thoughts on this are likely to evolve as the project progresses.

License

This project is dual-licensed under either:

at your option.

Contributing

See CONTRIBUTING.md.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.