Getting Started

• 1: Installing gitx
• 2: Using gitx
• 2.1: Basics
• 2.2: Keybinds
• 2.3: Custom Themes

1 - Installing gitx

Installation Script

The easiest way to install gitx is by using the installation script. Open your terminal and run the following command:

curl -sSL https://raw.githubusercontent.com/gitxtui/gitx/master/install.sh | bash

This script will automatically detect your operating system and architecture, download the latest release of gitx, and install it to /usr/local/bin.

Using go install

Requires go to be installed on your system:

go install github.com/gitxtui/gitx/cmd/gitx@latest

This will download the correct binary according to your operating system and place it at ~/go/bin/gitx.

Manual Installation

If you prefer to install gitx manually, you can download the latest release from the GitHub Releases page.

Download the appropriate .tar.gz file for your operating system and architecture. Extract the archive:

tar -xzf gitx_*.tar.gz

Move the gitx binary to a directory in your $PATH, for example:

sudo mv gitx /usr/local/bin/

To verify that gitx is installed correctly, change to a directory containing a git repo and run:

gitx --version

Next steps:

• Learn gitx: Learn how to use gitx!
• Tutorials: Check out some tutorials for git!

2 - Using gitx

2.1 - Basics

2.2 - Keybinds

Overview

gitx is a keyboard-driven application with customizable keybindings. Every action in gitx can be remapped to your preferred key combination. This guide covers all available keybinds, how to customize them, and best practices for configuring your keyboard shortcuts.

Configuration

Keybindings are configured in your gitx configuration file located at ~/.config/gitx/config.toml. The keybindings section uses the following format:

[keybindings]
action_name = "key_combination"

Key Specification Format

Keys can be specified in several ways:

• Single keys: a, 1, !, etc.
• Special keys: enter, esc, tab, space, up, down, left, right, backspace, delete, home, end, pgup, pgdn
• Modifier combinations: ctrl+c, shift+tab, alt+x
• Multiple key options: q,ctrl+c (either key will trigger the action)

You can specify multiple alternative keybindings for a single action by separating them with commas.

Default Keybindings

Here are all the default keybindings organized by category:

Navigation

Files & Changes

Branches

Commits

Stash

Miscellaneous

Customizing Keybindings

Basic Customization

To customize a keybinding, add it to the [keybindings] section in your ~/.config/gitx/config.toml file. For example:

[keybindings]
# Use 'l' instead of 'j' to move down
down = "l"

# Use 'h' instead of 'k' to move up  
up = "h"

# Create a new branch with 'b'
new_branch = "b"

Multiple Key Options

You can specify multiple keys that trigger the same action by separating them with commas:

[keybindings]
# Stage with either 'a' or 's'
stage_item = "a,s"

# Quit with 'q', ctrl+c, or ctrl+d
quit = "q,ctrl+c,ctrl+d"

# Switch themes with ctrl+t or ctrl+n
switch_theme = "ctrl+t,ctrl+n"

Vim-like Configuration

Many users prefer vim-like keybindings. Here’s a complete vim-inspired configuration:

[keybindings]
# Navigation
up = "k"
down = "j"
left = "h"
right = "l"

# File operations
stage_item = "a"
commit = "c"
discard = "d"
stash = "z"

# Branch operations
new_branch = "b"
checkout = "o"
delete_branch = "x"
rename_branch = "r"

# Commit operations  
amend_commit = "e"
revert = "v"
reset_to_commit = "R"

# General
toggle_help = "?"
quit = "q"
escape = "esc"

Emacs-like Configuration

For those preferring Emacs-style bindings:

[keybindings]
# Navigation (Ctrl+N/P for next/previous, Ctrl+F/B for forward/backward)
down = "ctrl+n"
up = "ctrl+p"

# Word navigation
focus_next = "ctrl+z"
focus_prev = "ctrl+shift+z"

# Common operations
stage_item = "ctrl+a"
discard = "ctrl+d"
stash = "ctrl+s"
commit = "ctrl+x"

# Help and exit
toggle_help = "ctrl+h"
quit = "ctrl+c"
escape = "esc"

Arrow Key Configuration

If you prefer using arrow keys for navigation:

[keybindings]
# Use arrow keys
up = "up"
down = "down"
left = "left"
right = "right"

# Keep other keys for actions
stage_item = "a"
commit = "c"
new_branch = "n"

Advanced Examples

Minimal Keybinding Set

If you only want to change a few keybindings and keep most defaults:

[keybindings]
# Only customize your most-used actions
commit = "w"
stage_item = "s"
toggle_help = "h"

Dvorak Layout Configuration

For Dvorak keyboard layout users:

[keybindings]
# Dvorak layout mappings (mapped to QWERTY position)
up = "o"
down = "a"
left = "s"
right = "e"

# Common operations using Dvorak
stage_item = "j"
commit = "b"
discard = "h"
new_branch = "c"

Macros and Complex Workflows

While gitx doesn’t support full macro systems, you can use common key combinations for your workflow:

[keybindings]
# Quick workflow keys
new_branch = "n"
stage_all = "s"
commit = "c"
checkout = "o"
delete_branch = "x"

# Focus shortcuts
focus_files = "2"
focus_branches = "3"
focus_commits = "4"

Tips and Best Practices

1. Avoid Conflicts: Don’t map the same key combination to multiple actions
2. Use Modifiers Wisely: Reserve Ctrl combinations for important actions you use frequently
3. Consistency: Try to keep your keybindings consistent with tools you already use (vim, tmux, etc.)
4. Test Before Committing: After changing a keybinding, test it in gitx to ensure it works
5. Document Your Setup: Keep notes on your custom keybindings for future reference
6. Preserve Escape: It’s recommended to keep escape bound to esc as a safe abort key

Viewing Active Keybindings

When inside gitx, press ? (or your custom toggle_help key) to view the current active keybindings. This will show all keybindings for the currently focused panel.

Configuration File Location

Your keybindings are stored in: ~/.config/gitx/config.toml

If this file doesn’t exist, gitx will create it with default settings the first time you run the application.

2.3 - Custom Themes

Overview

gitx comes with built-in themes and supports fully customizable user-defined themes. You can modify colors, styles, and the overall appearance of the interface. This guide covers using built-in themes and creating your own custom themes.

Built-in Themes

gitx includes the following built-in themes:

• GitHub Dark (default) - A clean dark theme based on GitHub’s color palette
• Gruvbox - A retro groove color scheme

Using Built-in Themes

To switch between built-in themes:

1. In gitx: Press ctrl+t (or your custom switch_theme key) to cycle through available themes
2. In config file: Edit ~/.config/gitx/config.toml and change the theme:

theme = "Gruvbox"

Built-in Theme Colors

GitHub Dark Theme

GitHub Dark is the default theme with GitHub’s iconic color scheme:

Background: #0d1117
Foreground: #c9d1d9

Normal Colors:
  Black:    #24292E    | Bright Black:    #6e7681
  Red:      #ff7b72    | Bright Red:      #ffa198
  Green:    #3fb950    | Bright Green:    #56d364
  Yellow:   #d29922    | Bright Yellow:   #e3b341
  Blue:     #58a6ff    | Bright Blue:     #79c0ff
  Magenta:  #bc8cff    | Bright Magenta:  #d2a8ff
  Cyan:     #39c5cf    | Bright Cyan:     #56d4dd
  White:    #b1bac4    | Bright White:    #f0f6fc

Dark Colors (for selected items):
  Dark Black:    #1b1f23
  Dark Red:      #d73a49
  Dark Green:    #28a745
  Dark Yellow:   #dbab09
  Dark Blue:     #2188ff
  Dark Magenta:  #a041f5
  Dark Cyan:     #12aab5
  Dark White:    #8b949e

Gruvbox Theme

Gruvbox is a warm, retro-inspired color scheme:

Background: #282828
Foreground: #ebdbb2

Normal Colors:
  Black:    #282828    | Bright Black:    #928374
  Red:      #cc241d    | Bright Red:      #fb4934
  Green:    #98971a    | Bright Green:    #b8bb26
  Yellow:   #d79921    | Bright Yellow:   #fabd2f
  Blue:     #458588    | Bright Blue:     #83a598
  Magenta:  #b16286    | Bright Magenta:  #d3869b
  Cyan:     #689d6a    | Bright Cyan:     #8ec07c
  White:    #a89984    | Bright White:    #ebdbb2

Dark Colors (for selected items):
  Dark Black:    #1d2021
  Dark Red:      #9d0006
  Dark Green:    #79740e
  Dark Yellow:   #b57614
  Dark Blue:     #076678
  Dark Magenta:  #8f3f71
  Dark Cyan:     #427b58
  Dark White:    #928374

Creating Custom Themes

Custom themes are stored as TOML files in ~/.config/gitx/themes/. Each custom theme file defines a color palette that gitx uses to render the interface.

Theme File Location

Create your custom theme files in: ~/.config/gitx/themes/

The directory will be created automatically when gitx first runs. If it doesn’t exist, create it manually:

mkdir -p ~/.config/gitx/themes

Theme File Format

Each theme is a TOML file with the following structure:

# Global foreground and background colors
fg = "#e8e8e8"
bg = "#1a1a1a"

# Standard colors (8 colors)
[normal]
Black = "#2d2d2d"
Red = "#f2777a"
Green = "#99cc99"
Yellow = "#ffcc99"
Blue = "#6699cc"
Magenta = "#cc99cc"
Cyan = "#99cccc"
White = "#e8e8e8"

# Light/bright colors (8 colors)
[bright]
Black = "#999999"
Red = "#ff9999"
Green = "#99ff99"
Yellow = "#ffff99"
Blue = "#99ccff"
Magenta = "#ff99ff"
Cyan = "#99ffff"
White = "#ffffff"

# Dark colors for selected items
[dark]
Black = "#000000"
Red = "#cc0000"
Green = "#00cc00"
Yellow = "#cccc00"
Blue = "#0000cc"
Magenta = "#cc00cc"
Cyan = "#00cccc"
White = "#999999"

Color Format

Colors must be specified in hexadecimal format with a # prefix, e.g., #ff7b72. You can use any 6-digit hex color code.

Creating Your First Custom Theme

Here’s an example of creating a minimalist theme:

1. Create the file ~/.config/gitx/themes/minimal.toml:

# Minimal Light Theme
fg = "#000000"
bg = "#ffffff"

[normal]
Black = "#000000"
Red = "#990000"
Green = "#009900"
Yellow = "#999900"
Blue = "#000099"
Magenta = "#990099"
Cyan = "#009999"
White = "#cccccc"

[bright]
Black = "#666666"
Red = "#ff0000"
Green = "#00ff00"
Yellow = "#ffff00"
Blue = "#0000ff"
Magenta = "#ff00ff"
Cyan = "#00ffff"
White = "#ffffff"

[dark]
Black = "#333333"
Red = "#660000"
Green = "#006600"
Yellow = "#666600"
Blue = "#000066"
Magenta = "#660066"
Cyan = "#006666"
White = "#999999"

2. In gitx, change your theme in ~/.config/gitx/config.toml:

theme = "minimal"

Note: The theme name is the filename without the .toml extension.

Theme Examples

Dracula Theme

A popular dark theme with vibrant colors:

fg = "#f8f8f2"
bg = "#282a36"

[normal]
Black = "#21222c"
Red = "#ff5555"
Green = "#50fa7b"
Yellow = "#f1fa8c"
Blue = "#69b7f0"
Magenta = "#ff79c6"
Cyan = "#8be9fd"
White = "#f8f8f2"

[bright]
Black = "#6272a4"
Red = "#ff6e6e"
Green = "#69ff94"
Yellow = "#ffffa5"
Blue = "#d6acff"
Magenta = "#ff92df"
Cyan = "#a4ffff"
White = "#ffffff"

[dark]
Black = "#000000"
Red = "#cc0000"
Green = "#00cc00"
Yellow = "#cccc00"
Blue = "#0000cc"
Magenta = "#cc00cc"
Cyan = "#00cccc"
White = "#666666"

Solarized Dark

A precision colors theme for machines and people:

fg = "#839496"
bg = "#002b36"

[normal]
Black = "#073642"
Red = "#dc322f"
Green = "#859900"
Yellow = "#b58900"
Blue = "#268bd2"
Magenta = "#d33682"
Cyan = "#2aa198"
White = "#eee8d5"

[bright]
Black = "#586e75"
Red = "#cb4b16"
Green = "#93a1a1"
Yellow = "#839496"
Blue = "#657b83"
Magenta = "#6c71c4"
Cyan = "#63b132"
White = "#fdf6e3"

[dark]
Black = "#000000"
Red = "#990000"
Green = "#009900"
Yellow = "#999900"
Blue = "#000099"
Magenta = "#990099"
Cyan = "#009999"
White = "#666666"

Nord Theme

An arctic, north-bluish color palette:

fg = "#eceff4"
bg = "#2e3440"

[normal]
Black = "#3b4252"
Red = "#bf616a"
Green = "#a3be8c"
Yellow = "#ebcb8b"
Blue = "#81a1c1"
Magenta = "#b48ead"
Cyan = "#88c0d0"
White = "#eceff4"

[bright]
Black = "#4c566a"
Red = "#d08770"
Green = "#c3e88d"
Yellow = "#ffeb3b"
Blue = "#8fbcbb"
Magenta = "#c9a87c"
Cyan = "#8fbcbb"
White = "#ffffff"

[dark]
Black = "#0d0e11"
Red = "#7a1515"
Green = "#1d5e1d"
Yellow = "#5d5d00"
Blue = "#0d0d4d"
Magenta = "#4d004d"
Cyan = "#004d4d"
White = "#4d4d4d"

One Dark

Atom’s popular One Dark theme:

fg = "#abb2bf"
bg = "#282c34"

[normal]
Black = "#1e2127"
Red = "#e06c75"
Green = "#98c379"
Yellow = "#d19a66"
Blue = "#61afef"
Magenta = "#c678dd"
Cyan = "#56b6c2"
White = "#abb2bf"

[bright]
Black = "#5c6370"
Red = "#e06c75"
Green = "#98c379"
Yellow = "#d19a66"
Blue = "#61afef"
Magenta = "#c678dd"
Cyan = "#56b6c2"
White = "#c8ccd4"

[dark]
Black = "#000000"
Red = "#990000"
Green = "#009900"
Yellow = "#999900"
Blue = "#000099"
Magenta = "#990099"
Cyan = "#009999"
White = "#666666"

Using Custom Themes

Once you’ve created a custom theme file, you can use it by:

1. Via config file: Edit ~/.config/gitx/config.toml and set:

   theme = "your_theme_name"
   

   (Use the filename without .toml extension)

2. Via keybinding: Use ctrl+t (or your custom switch_theme key) to cycle through all available themes, including your custom ones.

Color Reference for UI Elements

While gitx automatically generates the complete UI styling from your color palette, here’s what each color group is used for:

• Normal Colors: Used for regular text, UI elements, and general content
• Bright Colors: Used for highlights, emphasis, and important elements
• Dark Colors: Used for selected items, active focus states, and backgrounds
• Foreground (fg): Default text color
• Background (bg): Default background color

Tips for Creating Themes

1. Test Your Palette: Create high-contrast between foreground and background for readability
2. Use Consistent Hues: Keep related colors in the same hue family for visual consistency
3. Consider Accessibility: Ensure sufficient contrast ratios for people with color vision deficiency
4. Name Meaningfully: Use descriptive names for your theme files (e.g., monokai_dark.toml instead of theme1.toml)
5. Validate Colors: Use online tools to check color contrast and hex validity
6. Test in gitx: Launch gitx after creating a theme to see how it looks in practice

Color Tools

These tools can help you create and validate custom themes:

• Colorhexa - Hex color lookup and conversion
• WebAIM Contrast Checker - Check color contrast ratios
• Coolors - Color palette generator
• Vibrancy - iOS color palette generator

Troubleshooting

Theme not appearing in the theme switcher:

• Ensure the file is in ~/.config/gitx/themes/ directory
• Verify the filename ends with .toml
• Check that all color values are valid hex codes

Colors look wrong:

• Verify all color values use the # prefix (e.g., #ff0000)
• Ensure hex codes are 6 digits long
• Check that the TOML syntax is valid

gitx crashes when loading theme:

• Use a simple theme with the example above as a template
• Verify no duplicate color entries exist
• Check that there are no special characters in color values

Configuration File Location

Your theme configuration is determined by the theme setting in: ~/.config/gitx/config.toml

Your custom theme files are stored in: ~/.config/gitx/themes/