# twm

Tmux Workspace Manager

`twm` is a highly performant, customizable tool to manage workspaces as `tmux` sessions. Sensible defaults can get you up and running with zero configuration, or you can set it up to fit any workflow you like.


![twm](https://raw.githubusercontent.com/vinnymeller/twm-assets/e1a390f8aaa58994059d10271452f8fea5f94a26/twm.gif)

### Table of Contents
#### [CLI Usage](#usage)
#### [Installation Instructions](#installation)
#### [Exposed Environment Variables](#environment-variables)
#### [Configuring twm](#configuration)
#### [Configuration Recipes](#recipes)
#### [Contribution Guidelines](#contributing)

## 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:
  -e, --existing
          Prompt user to select an existing tmux session to attach to.

          This shouldn't be used with other options.

  -g, --group
          Prompt user to start a new session in the same group as an existing session.

          Setting this option will cause `-l/--layout` and `-p/--path` to be ignored.

  -d, --dont-attach
          Don't attach to the workspace session after opening it

  -l, --layout
          Prompt user to select a globally-defined layout to open the workspace with.

          Using this option will override any other layout definitions that would otherwise automatically be used when opening the workspace.

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

          When setting this option, you should be aware that twm will not "see" this session when performing other automatic actions. For example, if you have a workspace at ~/foobar and run `twm -n jimbob -p ~/foobar`, and then run `twm` and select `~/foobar` from the picker, a new session `foobar` will be created. If you then run `twm -g` and select `foobar`, `foobar-1` will be created in the `foobar` group.

      --make-default-config
          Make default configuration file.

          By default will attempt to write a default configuration file and configuration schema in `$XDG_CONFIG_HOME/twm/` Using `-p/--path` with this flag will attempt to write the files to the folder specified. twm will not overwrite existing files. You will be prompted to rename/move the existing files before retrying.

      --make-default-layout-config
          Make default local layout configuration file.

          Will attempt to create `.twm.yaml` in the current directory. Will not overwrite existing files. You can use `-p/--path <PATH>` to specify a different directory to write the file to.

      --print-config-schema
          Print the configuration file (twm.yaml) schema.

          This can be used with tools (e.g. language servers) to provide autocompletion and validation when editing your configuration.

      --print-layout-config-schema
          Print the local layout configuration file (.twm.yaml) schema.

          This can be used with tools (e.g. language servers) to provide autocompletion and validation when editing your configuration.

      --print-bash-completion
          Print bash completions to stdout

      --print-zsh-completion
          Print zsh completions to stdout

      --print-fish-completion
          Print fish completions to stdout

      --print-man
          Print man(1) page to stdout

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

These can be used in many possible ways:
- Instead of defining all your setup commands in a workspace-type-specific layout, you could have a 1 shared setup script defined globally that runs on workspace entry that checks `TWM_TYPE` for type-specific setup
- You can use `TWM_ROOT` to perform actions if the workspace is in within a specific directory
- You can check `TWM` to ensure you handle manually-created sessions differently than `twm`-created sessions in some automation task

Additionally, setting the `TWM_CONFIG_FILE` env var will override the default config search path. If your config file is in a non-standard location, you can test twm with the default configuration with `TWM_CONFIG_FILE= twm`, or if your configuration is in the standard location, `TWM_CONFIG_FILE=/dev/null twm` will do.

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

### Cargo 

The easiest way to install is to use Cargo:
```bash
cargo install twm
```

### Nix

If you use Nix, it is available in [nixpkgs](https://search.nixos.org/packages?channel=unstable&show=twm&from=0&size=50&sort=relevance&type=packages&query=twm) as well as being packaged in this repo's  flake.


### Completion

If you're using Nix, completion scripts are automatically installed with `twm`, both from this flake and nixpkgs.

I don't believe it is packaged on any other OS. You can manually set up shell completions by putting the following in your shell config:

#### Bash

```
# ~/.bashrc
eval "$(twm --print-bash-completion)"
```

#### Zsh
```
# ~/.zshrc
eval "$(twm --print-zsh-completion)"
```

#### Fish
```
# ~/.config/fish/config.fish
twm --print-fish-completion | source
```

## Configuration

`twm` doesn't need any configuration to run. You can just install it and run `twm`, and the defaults should work for some.

To get a decent default configuration file, you can run `twm --make-default-config`, which will attempt to write two files: `$XDG_CONFIG_HOME/twm/{twm.yaml,twm.schema.json}`. 

You can pass `-p/--path <PATH>` with `--make-default-config` to write the files to a different folder.

If you use `yaml-language-server`, the default configuration file will automatically be set up to use the `twm.schema.json` file for validation and completion.

When you update `twm`, you can run `twm --print-config-schema > $XDG_CONFIG_HOME/twm/twm.schema.json` to ensure you have the latest schema file.

For a full list of configuration options with examples, see [CONFIGURATION.md](./doc/CONFIGURATION.md)

### Configuration Validation Examples

Here's what the in-editor config validation looks like in neovim with using `yaml-language-server`:

![twm configuration completion](https://raw.githubusercontent.com/vinnymeller/twm-assets/master/twm-config-completion.png)

![twm configuration validation](https://raw.githubusercontent.com/vinnymeller/twm-assets/master/twm-config-errors.png)


## Recipes

### tmux keybindings

Here are the basic twm bindings I personally use:

```tmux
# ~/.tmux.conf
bind f run-shell "tmux neww twm"
bind F run-shell "tmux neww twm -l"
bind s run-shell "tmux neww twm -e"  # i rebind the original `s` to `S` so I can still use it
bind g run-shell "tmux neww twm -g"
bind e run-shell "tmux switch -t $TWM_DEFAULT"  # i set TWM_DEFAULT in my shellrc, just a session that is always available as a scratch area
```

### Useful aliases / scripts

twm purposefully doesn't try to add features that are easily done with some light scripting. Here are a couple dumbed down examples of things I use:

```zsh
# ~/.zshrc
alias twm-fork='twmg() { gh repo fork --clone --default-branch-only --remote "$1" "$2"; twm -p "$2"; }; twmg'  # fork repo $1 at path $2 and open it in twm

# kill current session and switch to last/next/previous session
# i bind this to K in tmux
kt() {
  ORIG_SESS="$TWM_NAME"
  tmux switch -l || tmux switch -n || tmux switch -p
  tmux kill-session -t "$ORIG_SESS"
}

```

## Contributing

Contributions are of course welcome! It's not a huge project so I don't have a lot of guidelines. Make sure the tests (test*, for now :\\) pass. `cargo fmt`. `cargo clippy -- -D clippy::all`. That's all I can think of.


### Feature Philosophy

I avoid adding anything that doesn't have obvious value being *inside* `twm`. If something that can be done *well* with a simple shell script or similar, it probably should be.

#### Examples of things that won't be added:

- Opening a fuzzy finder to choose a session to kill. Simple shell script / easy enough to do with built-in tmux features. 
- Opening git worktree branches in windows. Use layouts for this. Detect when you're in a workspace with worktrees and run a script to open them how you want. This will always be more flexible than anything that would be built in.
- Cloning a git repository into a new workspace. This and the above are pretty specific to `tmux-sessionizer` but useful to highlight the differences in our goals. `twm` offers `-p` to open a workspace at a specific path, so such a functionality could be done with something as simple as an alias `alias twm-clone='git clone $1 $2 && twm -p $2'`. You can do the same with mercurial, svn, whatever you want to do.


#### Examples of things that could be added:

- Support for different multiplexers (e.g. Zellij). Abstracting the tmux-specific parts of `twm` into something that could be set up with different multiplexer backends could be a great addition. But I only use tmux/nobody has asked, so I haven't bothered.


#### Features that snuck their way in

There are some features I originally didn't want to add but have since been added anyways.
- Fuzzy finding existing sessions to attach to. Originally I figured it just makes more sense to leave that to built in tmux features, but when the request was made to add a feature to open a session in a group (`twm -g`), I had to add everything needed for `twm -e` anyways. Additionally, if you want to *fuzzy find* existing sessions, having that functionality outside `twm` would rely on some other  fuzzy finder. Part of the point of `twm` coming with its own builtin finder is avoid having to rely on other tools in the first place. Thus `twm -g` and `twm -e` were born. I think `-e` is the least useful thing that will ever be added to `twm`.


## License
[MIT](./LICENSE)


## Similar Projects

- [dmux](https://github.com/zdcthomas/dmux)
- [jrmoulton/tmux-sessionizer](https://github.com/jrmoulton/tmux-sessionizer)
- [ThePrimeagen/tmux-sessionizer](https://github.com/ThePrimeagen/.dotfiles/blob/602019e902634188ab06ea31251c01c1a43d1621/bin/.local/scripts/tmux-sessionizer)
- [tmux-sessionx](https://github.com/omerxx/tmux-sessionx)
- [tmuxinator](https://github.com/tmuxinator/tmuxinator)
- [tmuxp](https://github.com/tmux-python/tmuxp)