hyprsession 0.2.0

Saves hyprland sessions
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

# Hyprsession
## Overview
Implements session persistance for Hyprland. While the program is running it periodicly saves the command, workspace and other properties of running clients found by `hyprctl clients`. These are then saved to a file formatted as a Hyprland config file which can then be sourced so that the session is restored when Hyprland is restarted.

<a href="https://www.buymeacoffee.com/joshurtree" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-red.png" alt="Buy Me A Coffee" height="41" width="174"></a>

## Installation
#### Manual
As root run the command 
```
cargo install --root /usr/local hyprsession
``` 
Or install as a user by replacing `/usr/local` with your home directory. 

#### Arch Linux
Hyprsession can be installed via the AUR. By either running your aur package manager of choice or manually by running
```
git clone https://aur.archlinux.org/hyprsession.git
cd hyprsession
makepkg -i
```
#### NixOS
Add the input to your `flake.nix`
```
hyprsession.url = "github:joshurtree/hyprsession"
```

Then either add the package to your `configuration.nix` or use `${inputs.hyprsession.packages.${pkgs.system}.hyprsession}/bin/hyprsession` in place of `hyprsession` to run the program.

## Usage
To automaticly run the program in future sessions add the following line to your Hyprland config file (Usually at ~/.config/hypr/hyprland.conf)
```
exec-once = hyprsession
```
The same line can be added to your `home.nix` hyprland configuration if your are using Nix Home Manager.
If you want to save a session that is already running then run
```
hyprsession save-only &
```
or
```
hyprsession save-and-exit
```

## Options
Various options can be used to modify the behavior of Hyprsession.

### <mode>
One of
* default - Loads the session at startup the saves the current session at regular intervals.
* load - Load the session given by name (clears current session first)
* save - Save the current session 
* clear - Clear the current session (removes all windows)
* list - List all available sessions
* delete - Delete a session
* command - Create a command to deal with edge cases (see below)
 
### <name>
Name of the session or command

### <command>
Command to run (see below) 

### --load-time n
The period of time after loading a session that windows are modified to match virtual counterparts

### --save-interval n
This sets the interval in seconds between session saves. The default is 60 seconds.

### --session-path
This allows the user to save the session config in an alternative directory, by default its ~/.local/share/hyprsession. 

### --simulate
Only simulate loading and clearing of sessions

### --mode <mode> (depreciated)
Sets the mode the program runs in 
* Default - Loads the session at startup the saves the current session at regular intervals.
* SaveOnly - As above but skips loading the session
* LoadAndExit - Load the saved session then immediatly exit
* SaveAndExit - Save the current session then exit

## Command detection and fake commands
Detecting what command is needed to create any given window in wayland does not have a single uniform solution.
The information within the `/proc` directory is used to try and find this. If this doesn't yield a command available 
via $PATH then the `initial_class` of the window is checked followed by `initial_title`.  

With applications that come in the form of Flatpaks, Snaps or Electron apps this method does not produce a proper result. 
To solve this requires the use of fake commands. An example would be if you use the Firefox flatpak then runing
```
hyprsession command firefox "flatpak run org.mozilla.firefox"
```
This creates a script in the `~/.local/bin` directory that runs the correct command.

## Change log
### 0.1.1
* Changed --session-path option to point at base directory of session file
### 0.1.2
* Fixed bug which would crash program if no session file existed
### 0.1.3
* Fix fatal bug on Hyprland 0.4 that crashed the program while saving the session  
### 0.1.4
* Changed fullscreen dispatcher to use fullscreenmode and fixed FullscreenMode type issue (#2)
* Updated to latest alpha version of hyprland crate. Fixes panic on fetching clients (#1)
### 0.1.5
* Skip saving clients with duplicate pids (i.e. generated by the same application)
* Add option to retain clients with duplicate pids
### 0.1.6
* Handle special workspaces properly
* Handle wrapped programs in Nixos
### 0.2.0
* Breaking change: Remove the need to use '--mode' to specify what mode to launch the program in
* Introduce named sessions
* Improve method of finding originating command for clients
* Track client creation to try and better place them
* Introduce 'fake command' functionality to deal with programs complicated launch patterns (flatpak, snap etc.)
* Refactor code to allow potential future use as either standalone or as a client

## Development

### Running Tests
Along side the standard tests you can create a test within a vm using nix by running 
```bash
cd tests/vm-test
./run-test.sh
```

This will:
1. Build a NixOS VM with Hyprland and hyprsession
2. Start test applications (Firefox, terminal, calculator, etc.)
3. Save a session with `hyprsession save`
4. Clear the workspace and restore with `hyprsession load`  
5. Compare before/after states and report results

Test results are saved to `tests/test-results/` with detailed comparison data. The programs started can be changed by
editing `tests/vm-test/exec.conf`

## Thanks

Thank you to the following people for helping to improve this project

* Tie C (ticia)
* Isaac Hesslegrave (HeadedBranch)
* Hornet (fsilly)