Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/edeneast/tuxmux

Tmux session manager
https://github.com/edeneast/tuxmux

Last synced: about 1 month ago
JSON representation

Tmux session manager

Awesome Lists containing this project

README 

        
// Autogenerated. Edit doc/readme.adoc instead.

= Tuxmux



:license_link: https://github.com/EdenEast/tuxmux/blob/main/LICENSE

:apache: https://apache.org/licenses/LICENSE-2.0



image:https://github.com/EdenEast/tuxmux/actions/workflows/check.yml/badge.svg?style=svg[ci-badge, link="https://github.com/EdenEast/tuxmux/actions/workflows/check.yml"]

image:https://img.shields.io/crates/v/tuxmux[crates-io-badge, link="https://crates.io/crates/tuxmux"]

image:https://img.shields.io/badge/license-Apache2.0-blue.svg[license-badge, link="{apache}"]



[sidebar]

*_Tuxmux_ (_tux_)* is a session and window manager for tmux.



image::https://github.com/EdenEast/tuxmux/assets/2746374/d088cc35-e541-4595-8987-310269a3c66f[demo]



== 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



:leveloffset: 1



= Installation



== Cargo



[source,sh]

----

cargo install tuxmux

----



== Nix



[source,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



[source,sh]

----

cargo install --path .

----



== Completion



.Bash

[%collapsible]

====

Add this to the end of your config file (usually `~/.bashrc`):



[source,bash]

----

eval "$(tux completion bash)"

----

====



.Elvish

[%collapsible]

====

Add this to the end of your config file (usually `~/.elvish/rc.elv`):



[source,bash]

----

eval (tux completion elvish | slurp)

----

====



.Fish

[%collapsible]

====

Add this to the end of your config file (usually ~/.config/fish/config.fish):



[source,bash]

----

tux completion fish | source

----

====



.Powershell

[%collapsible]

====

Add this to the end of your config file (find it by running echo `$profile` in PowerShell):



[source,powershell]

----

Invoke-Expression (& { (tux compltion powershell | Out-String) })

----

====



.Zsh

[%collapsible]

====

Add this to the end of your config file (usually `~/.zshrc`):



[source,zsh]

----

eval "$(tux completion zsh)"

----



[IMPORTANT]

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`



:leveloffset!:

:leveloffset: 1



= Jumplist



image::https://github.com/EdenEast/tuxmux/assets/2746374/113f268c-ceb8-4b01-a28c-69676da778b0[]



:harpoon: https://github.com/ThePrimeagen/harpoon#-harpooning



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

link:{harpoon}[ThePrimeagen/harpoon]. 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.



[source,bash]

.shell

----

# 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.



[source,bash]

.~/.config/tmux.conf

----

# 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.



:leveloffset!:

:leveloffset: 1



= 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.



:leveloffset!:

:leveloffset: 1



= Configuration



Tuxmux uses https://kdl.dev[KDL] as its configuration language.



== Quickstart:



[source,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.



[%hardbreaks]

Type: `number`

Default: `5`



[source,javascript]

----

depth 3

----



=== 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.



[%hardbreaks]

Type: `boolean`

Default: `false`



[source,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)



[%hardbreaks]

Type: `string list`

Default: `{ - ".direnv" "node_modules" }`



[source,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)



[%hardbreaks]

Type: `string list`

Default: `{ - "~" }`



[source, 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)



[%hardbreaks]

Type: `string list`

Default: `{}`



[source, javascript]

----

paths {

  single default=false {

    - "~/.config/nvim"

  }

}

----



:leveloffset!:



== 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 link:{dotfiles}[dotfiles] and has grown into this utility program.



:dotfiles: https://github.com/EdenEast/nyx/blob/7f0c07964222450ec33823ee76ff97dca190162b/bin/tm



== Licence



Tuxmux is licensed under link:{apache}[Apache] License (Version 2).



See link:{license_link}[LICENSE] file for more details.