# twm
Tmux Workspace Manager
## Another one?
Yes - I was originally inspired to start using something to manage my tmux sessions by [ThePrimeagen's](https://github.com/ThePrimeagen/.dotfiles/blob/602019e902634188ab06ea31251c01c1a43d1621/bin/.local/scripts/tmux-sessionizer) tmux-sessionizer script. I used it for a bit, but wanted something more, that did a bit more.
That led me to [tmuxinator](https://github.com/tmuxinator/tmuxinator). I thought the concept of layouts was really cool, and it felt nice to use, but there are several drawbacks that are addressed by [dmux](https://github.com/zdcthomas/dmux).
Honestly I like dmux quite a bit but for some reason was annoyed by a dependency on `fzf`. After that I found the dependencyless [tmux-sessionizer](https://github.com/jrmoulton/tmux-sessionizer) that uses the Skim rust crate instead.
I felt like something for *my* workflow was missing from each of these, hence this thing.
## What features does it have?
- Fuzzy find workspaces to open in tmux
- Is able to open workspaces in tmux even if not run from within a tmux session
- Highly configurable
- Define different default behaviors for different workspace types
- Sets useful environment variables (prefixed with `TWM_`) within your sessions to simplify extending `twm`'s functionality with other scripts
I've explicitly avoided adding anything to `twm` that can be easily accomplished with scripts or other tools to a) avoid bloating this codebase and b) not force my workflow on anyone else.
With that said, if it is *possible* but particularly *difficult* to accomplish something with other tools, I'm open to adding it.
Examples of things that definitely won't be added:
- Killing a workspace session and opening the most recent/default/etc one. Very simple shell script.
Example I'm on the fence about:
- Support for git worktrees. `tmux-sessionizer` has this, but I don't like how it's implemented. I have my own script for handling worktrees, but I don't particularly love it either, and it's not a trivial script. I do like it better though.
## Usage
```
twm (tmux workspace manager) is a customizable tool for managing workspaces in tmux sessions.
Workspaces are defined as a directory matching any workspace pattern from your configuration. If no configuration is set, any directory containing a `.git` file/folder or a `.twm.yaml` file is considered a workspace.
Usage: twm [OPTIONS]
Options:
-l, --layout
Prompt user to select a globally-defined layout to open the workspace with.
Using this option will override any other layout definitions.
-p, --path <PATH>
Open the given path as a workspace.
Using this option does not require that the path be a valid workspace according to your configuration.
-n, --name <NAME>
Force the workspace to be opened with the given name.
twm will not store any knowledge of the fact that you manually named the workspace. I.e. if you open the workspace at path `/home/user/dev/api` and name it `jimbob`, and then open the same workspace again manually, you will have two instances of the workspace open with different names.
-d, --dont-attach
Don't attach to the workspace session after opening it
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
```
### Environment Variables
`twm` will set several environment variables within all sessions generated by it. They're there to help with scripts or keybinds you want to interact with `twm`. They are:
- `TWM` - set to `1` if the current shell is in a `twm` session
- `TWM_ROOT` - the root directory of the new workspace
- `TWM_TYPE` - the type of workspace. empty string if there was no workspace type defined.
- `TWM_NAME` - the name of the tmux session created by `twm`.
Example use cases:
- keybind or alias to return to the root of the current workspace
-
## Installation
The easiest way to install is to use Cargo:
```bash
cargo install twm
```
It is also available on NixOS via [nixpkgs](https://search.nixos.org/packages?channel=unstable&show=twm&from=0&size=50&sort=relevance&type=packages&query=twm)
## Configuration
See [CONFIGURATION.md](./doc/CONFIGURATION.md)
## Example `twm` tmux keybindings
```tmux
# ~/.tmux.conf
bind-key -r f run-shell "tmux neww twm"
bind-key -r F run-shell "tmux neww twm -l"
bind-key -r e run-shell "tmux switch -t $TWM_DEFAULT" # i set TWM_DEFAULT in my shellrc
```
## Contributing
Contributions are more than welcome! If there are workflows you think would be useful to add, or if you find a bug, please open an issue or PR. For style and linting, I simply use `cargo fmt` and `clippy::all`.
## License
GPL v2.0