# niri-tag

## tag-based window management for the [niri](https://github.com/YaLTeR/niri) compositor

niri-tag allows you to use a simple tagging-based system to manage your windows.

## how tags work

tag based management is relatively intuitive - sets of windows are assigned numeric tags. \
these tags are then de/activated to raise and lower the windows. \
only a single workspace is ever in active use per output.

## usage

### typical unix

first,\
clone the repo.\
build and install with cargo as per usual for rust projects on your platform.

next,\
set up niri-tag as a user-level service.\
for systemd users, something like the following should suffice:

````ini
# /etc/systemd/user/niri-tag.service
[Unit]
Description=Niri Tag Manager
PartOf=graphical-session.target

[Service]
ExecStart=/usr/bin/niri-tag
PrivateTmp=true
Restart=always
Type=notify

[Install]
WantedBy=graphical-session.target
````

niri's `exec-once` *should* also be okay, but the use of a service manager is highly recommended.

finally,\
set up niri binds using `tagctl` to control windows and tags as you see fit.

### nixos (flakes)

first,\
add the following to your flake inputs:
````nix
niri-tag = {
  url = "git+https://git.atagen.co/atagen/niri-tag";
  inputs.niri-flake.follows = "niri-flake"; 
  inputs.nixpkgs.follows = "nixpkgs";
}
````
it is assumed you use niri-flake, or else will use the `stable` package output; this is important for the niri IPC definitions.

next,\
- add `inputs.niri-tag.nixosModules.niri-tag` to your module imports
- add `services.niri-tag.enable = true;` somewhere in your config
- if you wish to use a stable niri instead of unstable from niri-flake (default), set `services.niri-tag.package = inputs.niri-tag.packages.${pkgs.system}.stable;`

finally,\
add binds to your niri configuration.

you will need the path of `tagctl`, which you can get with something like the following:
````nix
let
  niri-tag = inputs.niri-tag.packages.${pkgs.system}.unstable; # or stable
  tagctl = lib.getExe' niri-tag "tagctl";
in
...
````

### bindings

first,\
it is recommended that you unset all workspace related binds, as
switching workspaces or moving windows between them
while using tag management can cause unexpected behaviours.

next,\
set up:
- `Mod+Shift+$number` as a spawn bind for `tagctl toggle $number`
- `Mod+$number` as `tagctl toggle-tag $number`.

alternatively,\
you may bind as you see fit the tagctl commands `add` `remove` `toggle` for window tagging,
and `enable-tag` `disable-tag` `toggle-tag` for managing tags.

all commands (except `remove`) take a tag number from 1-255 after their command.

finally,\
you may now use the aforementioned binds to assign tags to windows and toggle the tags on and off to hide/reveal them.

enjoy !