# Tuxmux
  
***Tuxmux* (*tux*)** is a session and window manager for tmux.
# 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
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.
**shell**
``` 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.
**~/.config/tmux.conf**
``` 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.