From 993a074f05a9214c861a0359907cbbb61cac2544 Mon Sep 17 00:00:00 2001 From: shatrughan mishra Date: Thu, 5 Mar 2026 17:35:38 +0530 Subject: [PATCH] docs: add keybinds and custom themes documentation Signed-off-by: shatrughan mishra --- .../02_using_gitx/02_key_binds.md | 273 ++++++++++++ .../getting-started/02_using_gitx/03_theme.md | 414 ++++++++++++++++++ 2 files changed, 687 insertions(+) diff --git a/content/en/learn/getting-started/02_using_gitx/02_key_binds.md b/content/en/learn/getting-started/02_using_gitx/02_key_binds.md index 5571041..729d477 100644 --- a/content/en/learn/getting-started/02_using_gitx/02_key_binds.md +++ b/content/en/learn/getting-started/02_using_gitx/02_key_binds.md @@ -5,3 +5,276 @@ description: Setting custom keybinds in gitx weight: 2 type: "docs" --- + +## 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: + +```toml +[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 + +| Action | Default Key | Description | +|--------|-------------|-------------| +| `focus_next` | `tab` | Move to the next window | +| `focus_prev` | `shift+tab` | Move to the previous window | +| `focus_main` | `0` | Focus the commit graph (main window) | +| `focus_status` | `1` | Focus the status window | +| `focus_files` | `2` | Focus the files/changes window | +| `focus_branches` | `3` | Focus the branches window | +| `focus_commits` | `4` | Focus the commits window | +| `focus_stash` | `5` | Focus the stash window | +| `focus_command_log` | `6` | Focus the command log window | +| `up` | `k` or `↑` | Move up in lists | +| `down` | `j` or `↓` | Move down in lists | + +### Files & Changes + +| Action | Default Key | Description | +|--------|-------------|-------------| +| `stage_item` | `a` | Stage the selected file or change | +| `stage_all` | `space` | Stage all changes | +| `discard` | `d` | Discard changes in the selected file | +| `stash` | `s` | Stash the selected file | +| `stash_all` | `S` | Stash all changes | +| `commit` | `c` | Create a new commit | + +### Branches + +| Action | Default Key | Description | +|--------|-------------|-------------| +| `checkout` | `enter` | Checkout the selected branch | +| `new_branch` | `n` | Create a new branch | +| `delete_branch` | `d` | Delete the selected branch | +| `rename_branch` | `r` | Rename the selected branch | + +### Commits + +| Action | Default Key | Description | +|--------|-------------|-------------| +| `amend_commit` | `A` | Amend the last commit | +| `revert` | `v` | Revert the selected commit | +| `reset_to_commit` | `R` | Reset to the selected commit | + +### Stash + +| Action | Default Key | Description | +|--------|-------------|-------------| +| `stash_apply` | `a` | Apply a stash without removing it | +| `stash_pop` | `p` | Apply a stash and remove it | +| `stash_drop` | `d` | Delete the selected stash | + +### Miscellaneous + +| Action | Default Key | Description | +|--------|-------------|-------------| +| `switch_theme` | `ctrl+t` | Cycle through available themes | +| `toggle_help` | `?` | Show/hide the help panel | +| `escape` | `esc` | Cancel current action | +| `quit` | `q` or `ctrl+c` | Exit gitx | + +## Customizing Keybindings + +### Basic Customization + +To customize a keybinding, add it to the `[keybindings]` section in your `~/.config/gitx/config.toml` file. For example: + +```toml +[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: + +```toml +[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: + +```toml +[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: + +```toml +[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: + +```toml +[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: + +```toml +[keybindings] +# Only customize your most-used actions +commit = "w" +stage_item = "s" +toggle_help = "h" +``` + +### Dvorak Layout Configuration + +For Dvorak keyboard layout users: + +```toml +[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: + +```toml +[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. diff --git a/content/en/learn/getting-started/02_using_gitx/03_theme.md b/content/en/learn/getting-started/02_using_gitx/03_theme.md index 5826d53..8e66512 100644 --- a/content/en/learn/getting-started/02_using_gitx/03_theme.md +++ b/content/en/learn/getting-started/02_using_gitx/03_theme.md @@ -5,3 +5,417 @@ description: Setting custom themes in gitx weight: 3 type: "docs" --- + +## 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: + +```toml +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: + +```bash +mkdir -p ~/.config/gitx/themes +``` + +### Theme File Format + +Each theme is a TOML file with the following structure: + +```toml +# 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`: + +```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`: + +```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: + +```toml +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: + +```toml +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: + +```toml +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: + +```toml +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: + ```toml + 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](https://www.colorhexa.com/) - Hex color lookup and conversion +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) - Check color contrast ratios +- [Coolors](https://coolors.co/) - Color palette generator +- [Vibrancy](https://www.vibrancy.app/) - 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/`