# qbt-clean

A tool for cleaning up torrents in qBittorrent. The defining feature is that it attempts to identify groups of torrents that are the same content. For example torrents that are likely hard-linked or ref-linked to the same underlying data.

> [!warning]
> This is a tool to data data, it will do so. It is highly recommended to run in dry-run (the default) first and validate that it is deleting what you expect.
>
> Additionally this tool is very new and not particularly well tested. Additionally the configuration is constantly changing at these early stages.
>
> **USE AT YOUR OWN RISK**

## Commands

### simulate

Simulate is equivalent to `clean` except that it doesn't actually modify anything. Use it to see what would be cleaned.

```sh
qbt-clean --config=config.scfg simulate
```

### clean

Clean torrents until space target is reached.

```sh
qbt-clean --config=config.scfg clean
```

### groups

Show grows as well as info about them such as if they are pinned or not and what rank they are in the cleaning order. Use `--help` for more options.

```sh
qbt-clean --config=config.scfg groups
```

## Grouping

The current grouping is incredibly simple. It just sums up the size of substantial files in each torrent. Any files that share the exact same total size are considered a group.

## Config

### Operational Config

#### `target-free`

Clean up torrents until this much space is free on the filesystem.

Note: This assumes that each deleted group frees up the amount of the space of the torrent size. This can underestimate (if the backing blocks are still used by other files) or overestimate (if the torrents in the group did not share data).

```yaml
target-free: 100 GiB
```

#### `qbt-url`

The URL to interact with qBittorrent at. This should also contain the username and password for authentication.

```yaml
qbt-url: http://localhost:8080
```

### Requirements

These requirements prevent cleaning up torrents that shouldn't be. They are applied to each torrent in a group individually. Any torrent in a group that fails to satisfy a requirement will prevent the entire group from being removed.

The default values are been show.

#### `categories-allowed`

The torrent must be in one of these categories to be cleaned up.

There are no defaults (meaning that if this isn't set no torrents will match).

#### `last-activity-min`

If the torrent was active within this period it won't be cleaned up.

```yaml
last-activity-min: 7d
```

#### `names-pinned`

If the torrent name matches any of these regexes it won't be cleaned up. These must match the full name.

There are no defaults.

#### `trackers-pinned`

If any of the tracker URLs name match any of these regexes it won't be cleaned up. These must match the full tracker URL.

There are no defaults.

#### `seed-time-min`

If the total torrent seed time is less than this it won't be cleaned up.

```yaml
seed-time-min: 14d
```

#### `seeder-count-min`

If the torrent doesn't have this many seeders it won't be cleaned up.

```yaml
seeder-count-min: 3
```

#### `state-allowed`

If the torrent isn't in one of these states it won't be cleaned up. These can be specified with either the identifiers that qBittorrent uses or more consistent kebab-case versions.

```yaml
state-allowed:
	error
	missing-files
	stopped
	stopped-downloading
	stopped-uploading
	uploading-forced
	uploading-queued
	uploading-stalled
```

If this field is empty, then any state is allowed.

### Rules

Rules allow you to override the requirements for specific torrents. For example the following rule will avoid cleaning up Archive.org torrents unless they have at least a year of seed time. Note that this applies only to the specific torrent. Other torrents in the group may have less seed time when cleaned up.

```yaml
rules:
	:
		match:
			tracker-url:
				http://bt\d+.archive.org:6969/announce
		seed-time-min: 365d
```

Rules consist of a `match:` block which contains filters and then a set of requirements to override when the filters match. Only the **last** override for every requirement will apply.

Additionally, there is a special `pin` requirement that overrides any other requirement. So a filter that applies `pin: true` will prevent a torrent (and it's group) from ever being deleted. `pin: false` will prevent a torrent from ever holding a group alive (but other torrents in the group may keep it alive). Just like other requirements only the **last** `pin` rule that matches applies.

> [!warning]
> Be very careful with `pin: false`. It overrides **all** requirements and is very easy to delete more than you intended. For example do you have an "Important Never Delete" category? It won't be protected by the `categories-allowed` requirement anymore. So be very careful that all rules that apply `pin: false` are very particular about what you want to never pin.

#### any

The `any` filter takes a list of filters and matches if any of them match.

This example will set the minimum seeder count if either a specific tracker is on the torrent or it is in the `favourites` category.

```yaml
rules:
	:
		match:
			any:
				:
					tracker-url:
						https://tracker.example
				:
					categories:
						favourites
			seeder-count-min: 10
```

#### categories

The `categories` filter matches torrents that are in the given categories.

```yaml
rules:
	match:
		categories:
			Favourites
			Keep Forever
```

Note: There is also a `categories-allowed` requirement.

#### is-private

Match based on if the torrent is marked as private or not.

```yaml
rules:
	:
		match:
			is-private: true
```

#### last-activity

Match based on when the torrent was last active.

```yaml
rules:
	:
		match:
			last-activity:
				lt: 1d
```

#### leech-count

Match the number of leechers.

```yaml
rules:
	match:
		leech-count:
			gt: 10
```

#### name

Match any torrents who's name matches the regex.

```yaml
rules:
	:
		match:
			name:
				Arch.*\.iso
```

#### none

Match if none of the given filters match:

```yaml
rules:
	match:
		none:
			:
				seed-count:
					lt: 10
				leech-count:
					lt: 10
```

#### seed-time

Match based on the seed time for the torrent.

```yaml
rules:
	:
		match:
			seed-time:
				gt: 1h
```

#### ratio

Match based on the ratio of the torrent.

```yaml
rules:
	match:
		ratio:
			ge: 8
```

#### seed-count

Match the number of seeders.

```yaml
rules:
	match:
		seed-count:
			ge: 10
```

#### state

Match if the torrent state is in any of the listed states.

```yaml
rules:
	:
		match:
			state:
				stopped-downloading
				uploading-forced
```

#### tracker-msg

Match if any of the tracker's tracker messages matches any of the given regexes.

```
rules:
	:
		match:
			tracker-msg:
				[Uu]nregistered torrent
				Torrent has been deleted.
```

#### tracker-msg

Match if any of the tracker URLs match any of the given regexes.

```
rules:
	:
		match:
			tracker-url:
				http://bt\d+.archive.org:6969/announce
```

### Ranking

Ranking determines which torrents to delete first. The highest ranked torrents will be deleted until the desired space is reclaimed.

All ranking parameters take a floating point number and default to zero. If all ranking parameters are zero `seeder-count-weight: 1.0` will be applied.

#### `age-d-max-weight`

Rank based on the age of the oldest torrent in the group.

Note: If you want to prefer keeping older torrents the weight should be negative.

#### `copies-weight`

Rank based on number of torrents in the group.

Note: If you want to prefer keeping larger groups the weight should be negative.

#### `last-activity-d-weight`

Rank based on the last activity in the group.

#### `seeder-count-weight`

Rank based on total seeder count.

#### `size-weight`

Rank based on the size expected to be freed by deleting.

Note: This is roughly the size of a torrent in the group.
