created_at2023-09-29 23:04:17.272935
updated_at2023-12-30 19:16:57.357694
descriptionTmux utility for session and window management



# Tuxmux ![ci-badge](https://github.com/EdenEast/tuxmux/actions/workflows/check.yml/badge.svg?style=svg) ![crates-io-badge](https://img.shields.io/crates/v/tuxmux) ![license-badge](https://img.shields.io/badge/license-Apache2.0-blue.svg) ***Tuxmux* (*tux*)** is a session and window manager for tmux. ![293403109 26a7462f 8e97 4842 8fb0 6beeb7fe0244.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MDM4NzE1NjQsIm5iZiI6MTcwMzg3MTI2NCwicGF0aCI6Ii8yNzQ2Mzc0LzI5MzQwMzEwOS0yNmE3NDYyZi04ZTk3LTQ4NDItOGZiMC02YmVlYjdmZTAyNDQuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDIzMTIyOSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyMzEyMjlUMTczNDI0WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ODgzNDE0MGFkYjA3YzVlNmZiYzlkY2M2ODlkM2MwZWY2NjQ1MTE2YTYwMjA5ZWM3ZmY4MzMxZmE4YjY4ZDcwMiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ](https://private-user-images.githubusercontent.com/2746374/293403109-26a7462f-8e97-4842-8fb0-6beeb7fe0244.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MDM4NzE1NjQsIm5iZiI6MTcwMzg3MTI2NCwicGF0aCI6Ii8yNzQ2Mzc0LzI5MzQwMzEwOS0yNmE3NDYyZi04ZTk3LTQ4NDItOGZiMC02YmVlYjdmZTAyNDQuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDIzMTIyOSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyMzEyMjlUMTczNDI0WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ODgzNDE0MGFkYjA3YzVlNmZiYzlkY2M2ODlkM2MwZWY2NjQ1MTE2YTYwMjA5ZWM3ZmY4MzMxZmE4YjY4ZDcwMiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.SO12CXuXTGtOZCStW2ootD48qKeS45QJ1_iE5_SC4cA) # Features - Fuzzy find tmux sessions to create / attach. - Jump list to quickly open tmux sessions (harpoon like) - Keybinding support for jumping - Highly configurable - Support git worktrees on session creation # Installation ## Cargo ``` sh cargo install tuxmux ``` ## Nix ``` sh # Try out tuxmux with `nix run` nix run github:EdenEast/tuxmux # Create a devshell with `nix shell` nix shell github:EdenEast/tuxmux # Install into profile nix profile install github:EdenEast/tuxmux # Install from nixpkgs nix-env -iA nixpkgs.tuxmux ``` ## Source ``` sh cargo install --path . ``` ## Completion Add this to the end of your config file (usually `~/.bashrc`): ``` bash eval "$(tux completion bash)" ``` Add this to the end of your config file (usually `~/.elvish/rc.elv`): ``` bash eval (tux completion elvish | slurp) ``` Add this to the end of your config file (usually ~/.config/fish/config.fish): ``` bash tux completion fish | source ``` Add this to the end of your config file (find it by running echo `$profile` in PowerShell): ``` powershell Invoke-Expression (& { (tux compltion powershell | Out-String) }) ``` Add this to the end of your config file (usually `~/.zshrc`): ``` zsh eval "$(tux completion zsh)" ```
For completions to work, the above line must be added after compinit is called. You may have to rebuild your completions cache by running rm ~/.zcompdump\*; compinit.
### Nix If installed with nix the following are installed by default: - `Bash` - `Fish` - `Zsh` # Jumplist ![293401660 fcaf25f9 409f 40f8 a8e8 872655f07ffd.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MDM4NzA4ODEsIm5iZiI6MTcwMzg3MDU4MSwicGF0aCI6Ii8yNzQ2Mzc0LzI5MzQwMTY2MC1mY2FmMjVmOS00MDlmLTQwZjgtYThlOC04NzI2NTVmMDdmZmQuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDIzMTIyOSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyMzEyMjlUMTcyMzAxWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9N2M5NzRlODZlYTZjMDQ1NjgzMjdmYjcxOTM5NWIxYzg4ZDdhYjExZDBjNWY4YWRlOWU3YjJlMDNmMDEyMTc4ZiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ](https://private-user-images.githubusercontent.com/2746374/293401660-fcaf25f9-409f-40f8-a8e8-872655f07ffd.gif?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MDM4NzA4ODEsIm5iZiI6MTcwMzg3MDU4MSwicGF0aCI6Ii8yNzQ2Mzc0LzI5MzQwMTY2MC1mY2FmMjVmOS00MDlmLTQwZjgtYThlOC04NzI2NTVmMDdmZmQuZ2lmP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDIzMTIyOSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyMzEyMjlUMTcyMzAxWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9N2M5NzRlODZlYTZjMDQ1NjgzMjdmYjcxOTM5NWIxYzg4ZDdhYjExZDBjNWY4YWRlOWU3YjJlMDNmMDEyMTc4ZiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.w2PtClvo-BBPwXCtbupenuxMg8Uo_PyF6UC3bWCwQKA) Tuxmux includes a feature known as the "**Jump List,**" which is designed to streamline the process of navigating and attaching to different sessions quickly. This concept is inspired by the "harpooning" concept introduced in [ThePrimeagen/harpoon](https://github.com/ThePrimeagen/harpoon#-harpooning). The Jump List serves as a powerful tool to facilitate seamless interaction with multiple sessions. ## What is Harpooning? Harpooning is a concept from ThePrimeagen’s GitHub project, which involves quickly and efficiently attaching to different sessions or targets within a terminal environment. It’s a technique often used by developers and power users who work with multiple terminal sessions simultaneously. ## Using the Jump List The primary use case for the Jump List is to enable quick access and attachment to specific sessions through keybindings. Here’s how it works: Populating the Jump List Before you can use the Jump List, you need to populate it with the sessions you want to interact with. This can typically be done by defining a set of sessions or targets within your application’s configuration.
``` bash # Appends the path argument to the jumplist tux jump --path ~/.config/nvim # Append the current path to the jumplist tux jump --path . # Open the jumplist in your $EDITOR tux jump --edit ``` Navigating with Keybindings Once the Jump List is populated, you can use keybindings or keyboard shortcuts to navigate to a specific index within the list. Each index typically corresponds to a session or target. This allows you to jump to a desired session with a single key combination.
``` bash # Bind homerow keys to tuxmux jumplist indices bind-key -r J run-shell "tux jump --index 1" bind-key -r K run-shell "tux jump --index 2" bind-key -r L run-shell "tux jump --index 3" bind-key -r '"' run-shell "tux jump --index 4" ``` Seamless Session Attachment When you activate a specific index in the Jump List, the application will swiftly attach you to the corresponding session, streamlining the process of interacting with multiple sessions efficiently. # Git Worktree This application offers support for Git worktrees, allowing you to manage multiple worktrees within a Git repository more efficiently. When creating a Tmux session using this application, you’ll have the flexibility to choose which worktree to attach to if the repository contains multiple worktrees. When you create a Tmux session with this application, you may encounter situations where the Git repository contains multiple worktrees. To provide you with a seamless experience, the application will prompt you to choose which worktree you’d like to attach to within the Tmux session. # Configuration Tuxmux uses [KDL](https://kdl.dev) as its configuration language. ## Quickstart: ``` shell mkdir -p ~/.config/tuxmux tux --default-config > ~/.config/tuxmux/config.kdl ``` ## File locations Tuxmux loads configuration information from two types of sources, local and global. The file is determined by searching each path for the first `config.kdl` file. | Local | Global | |-------------------------|---------------------------| | `$TUXMUX_DATA_PATH` | `$TUXMUX_CONFIG_PATH` | | `$XDG_DATA_HOME/tuxmux` | `$XDG_CONFIG_HOME/tuxmux` | | `~/.local/share/tuxmux` | `~/.config/tuxmux` | Values defined in the local config file have presidence over global values. Values containing lists will be merged instead of overritten. ## Options Full list of values defined in `config.kdl`. ### depth Sets the maximux search depth for workspace paths. Type: `number` Default: `5` ``` javascript depth 3 ``` ### height Height of the fuzzy finder selection window. The value can be either a number or a string. A number represents the number of lines or entries to be displayed. A string can be either the string "full" meaning fullscreen or a number followed by a '%' (percent sign). The percentage is the percentage of the terminals hight to be used. Type: `string | number` Default: `50%` ``` javascript height 10 ``` ### default_worktree Select the repositories remote default branch if multiple worktrees are found. If the default worktree cannot be found the fallback will be to select the correct one. Type: `boolean` Default: `false` ``` javascript default_worktree true ``` ### exclude_paths Workspace directory crawler will prune the paths containing any of these components. Optional arguments: - default: (boolean) Append to default value if true (Default: true) Type: `string list` Default: `{ - ".direnv" "node_modules" }` ``` javascript exclude_paths default=false { - ".direnv" - "node_modules" } ``` ### paths Configure the list of search paths used to search for valid workspaces. Tux uses these valid workspaces as options to attach to. #### paths.workspace Workspace paths are paths to recursivly search to find valid workspaces. Tux will recursivly search the workspace paths until the max depth is reached. To override the default workspace value set optional `default=false` Optional arguments: - default: (boolean) Append to default value if true (Default: true) Type: `string list` Default: `{ - "~" }` ``` javascript paths { workspaces default=false { - "~/code" } } ``` #### paths.single Single paths are paths that are added to the list of valid workspace paths. This is useful if you want to add a path that would not be defined as a valid workspace. Optional arguments: - default: (boolean) Append to default value if true (Default: true) Type: `string list` Default: `{}` ``` javascript paths { single default=false { - "~/.config/nvim" } } ``` # Development Tuxmux is currently under development and subject to change before a `v1` release. Have an idea for tuxmux? Open an issue or fork the project and create a PR. Tuxmux was originally a shell script in my [dotfiles]({dotfiles}) and has grown into this utility program. # Licence Tuxmux is licensed under [Apache](https://apache.org/licenses/LICENSE-2.0) License (Version 2). See [LICENSE](https://github.com/EdenEast/tuxmux/blob/main/LICENSE) file for more details.
Commit count: 159

cargo fmt