Skip to content

feat: add per-tag category display options #1336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Sola-ris wants to merge 12 commits into
base: main
Choose a base branch
from
Open

feat: add per-tag category display options #1336

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
d56e870
feat: add category exclusions.
Sola-ris Mar 30, 2026
a9447d0
bump DB_VERSION to 104, update test_db_migrations.
Sola-ris Mar 30, 2026
f2f0626
add translation keys.
Sola-ris Mar 30, 2026
e118483
make include_button a checkbox, cleanup.
Sola-ris Mar 31, 2026
66742d9
add missing translation for the properties label.
Sola-ris Mar 31, 2026
fa8b2aa
add tests.
Sola-ris Apr 2, 2026
8c68cb4
update docs.
Sola-ris Apr 2, 2026
431b201
fix categories when creating new tags.
Sola-ris Apr 2, 2026
c5aed0d
link PR in library-changes.md.
Sola-ris Apr 2, 2026
26710a1
fix: don't show categories for tags that define the category.
Sola-ris Apr 4, 2026
f9aa0f5
fix: persist exclusion_ids on all relevant add_tag calls.
Sola-ris Apr 4, 2026
d6a65d6
fix formatting.
Sola-ris Apr 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 38 additions & 30 deletions docs/library-changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Legacy (JSON) library save format versions were tied to the release version of t
### Versions 1.0.0 - 9.4.2

| Used From | Format | Location |
| --------- | ------ | --------------------------------------------- |
|-----------|--------|-----------------------------------------------|
| v1.0.0 | JSON | `<Library Folder>`/.TagStudio/ts_library.json |

The legacy database format for public TagStudio releases [v9.1](https://github.com/TagStudioDev/TagStudio/tree/Alpha-v9.1) through [v9.4.2](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.4.2). Variations of this format had been used privately since v1.0.0.
Expand Down Expand Up @@ -49,7 +49,7 @@ These versions were used while developing the new SQLite file format, outside an
### Version 6

| Used From | Format | Location |
| ------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
|---------------------------------------------------------------------------------|--------|-------------------------------------------------|
| [v9.5.0-pr1](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.0-pr1) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

The first public version of the SQLite save file format.
Expand All @@ -61,74 +61,82 @@ Migration from the legacy JSON format is provided via a walkthrough when opening
### Version 7

| Used From | Format | Location |
| ------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
|---------------------------------------------------------------------------------|--------|-------------------------------------------------|
| [v9.5.0-pr2](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.0-pr2) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Repairs "Description" fields to use a TEXT_LINE key instead of a TEXT_BOX key.
- Repairs tags that may have a disambiguation_id pointing towards a deleted tag.
- Repairs "Description" fields to use a TEXT_LINE key instead of a TEXT_BOX key.
- Repairs tags that may have a disambiguation_id pointing towards a deleted tag.

---

### Version 8

| Used From | Format | Location |
| ------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
|---------------------------------------------------------------------------------|--------|-------------------------------------------------|
| [v9.5.0-pr4](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.0-pr4) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Adds the `color_border` column to the `tag_colors` table. Used for instructing the [secondary color](colors.md#secondary-color) to apply to a tag's border as a new optional behavior.
- Adds three new default colors: "Burgundy (TagStudio Shades)", "Dark Teal (TagStudio Shades)", and "Dark Lavender (TagStudio Shades)".
- Updates Neon colors to use the new `color_border` property.
- Adds the `color_border` column to the `tag_colors` table. Used for instructing the [secondary color](colors.md#secondary-color) to apply to a tag's border as a new optional behavior.
- Adds three new default colors: "Burgundy (TagStudio Shades)", "Dark Teal (TagStudio Shades)", and "Dark Lavender (TagStudio Shades)".
- Updates Neon colors to use the new `color_border` property.

---

### Version 9

| Used From | Format | Location |
| ----------------------------------------------------------------------- | ------ | ----------------------------------------------- |
|-------------------------------------------------------------------------|--------|-------------------------------------------------|
| [v9.5.2](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.2) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Adds the `filename` column to the `entries` table. Used for sorting entries by filename in search results.
- Adds the `filename` column to the `entries` table. Used for sorting entries by filename in search results.

---

### Version 100

| Used From | Format | Location |
| ---------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
|------------------------------------------------------------------------------------------------------|--------|-------------------------------------------------|
| [74383e3](https://github.com/TagStudioDev/TagStudio/commit/74383e3c3c12f72be1481ab0b86c7360b95c2d85) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Introduces built-in minor versioning
- The version number divided by 100 (and floored) constitutes the **major** version. Major version indicate breaking changes that prevent libraries from being opened in TagStudio versions older than the ones they were created in.
- Values more precise than this ("ones" through "tens" columns) constitute the **minor** version. These indicate minor changes that don't prevent a newer library from being opened in an older version of TagStudio, as long as the major version is not also increased.
- Swaps `parent_id` and `child_id` values in the `tag_parents` table
- Introduces built-in minor versioning
- The version number divided by 100 (and floored) constitutes the **major** version. Major version indicate breaking changes that prevent libraries from being opened in TagStudio versions older than the ones they were created in.
- Values more precise than this ("ones" through "tens" columns) constitute the **minor** version. These indicate minor changes that don't prevent a newer library from being opened in an older version of TagStudio, as long as the major version is not also increased.
- Swaps `parent_id` and `child_id` values in the `tag_parents` table

#### Version 101

| Used From | Format | Location |
| ----------------------------------------------------------------------- | ------ | ----------------------------------------------- |
|-------------------------------------------------------------------------|--------|-------------------------------------------------|
| [v9.5.4](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.4) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Deprecates the `preferences` table, set to be removed in a future TagStudio version.
- Introduces the `versions` table
- Has a string `key` column and an int `value` column
- The `key` column stores one of two values: `'INITIAL'` and `'CURRENT'`
- `'INITIAL'` stores the database version number in which in was created
- Pre-existing databases set this number to `100`
- `'CURRENT'` stores the current database version number
- Deprecates the `preferences` table, set to be removed in a future TagStudio version.
- Introduces the `versions` table
- Has a string `key` column and an int `value` column
- The `key` column stores one of two values: `'INITIAL'` and `'CURRENT'`
- `'INITIAL'` stores the database version number in which in was created
- Pre-existing databases set this number to `100`
- `'CURRENT'` stores the current database version number

#### Version 102

| Used From | Format | Location |
| ----------------------------------------------------------------------- | ------ | ----------------------------------------------- |
|-------------------------------------------------------------------------|--------|-------------------------------------------------|
| [v9.5.4](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.4) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Applies repairs to the `tag_parents` table created in [version 100](#version-100), removing rows that reference tags that have been deleted.
- Applies repairs to the `tag_parents` table created in [version 100](#version-100), removing rows that reference tags that have been deleted.

#### Version 103

| Used From | Format | Location |
| ----------------------------------------------------------------------- | ------ | ----------------------------------------------- |
| Used From | Format | Location |
|--------------------------------------------------------------|--------|-------------------------------------------------|
| [#1139](https://github.com/TagStudioDev/TagStudio/pull/1139) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Adds the `is_hidden` column to the `tags` table (default `0`). Used for excluding entries tagged with hidden tags from library searches.
- Sets the `is_hidden` field on the built-in Archived tag to `1`, to match the Archived tag now being hidden by default.
- Adds the `is_hidden` column to the `tags` table (default `0`). Used for excluding entries tagged with hidden tags from library searches.
- Sets the `is_hidden` field on the built-in Archived tag to `1`, to match the Archived tag now being hidden by default.

#### Version 104

| Used From | Format | Location |
|--------------------------------------------------------------|--------|-------------------------------------------------|
| [#1336](https://github.com/TagStudioDev/TagStudio/pull/1336) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |

- Introduces the `category_exclusions` table. Used for excluding a tag from being displayed in a specific category
22 changes: 12 additions & 10 deletions docs/tags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Tags are discrete objects that represent some attribute. This could be a person,

TagStudio tags do not share the same naming limitations of many other tagging solutions. The key standouts of tag names in TagStudio are:

- Tag names do **NOT** have to be unique
- Tag names are **NOT** limited to specific characters
- Tags can have **aliases**, a.k.a. alternate names to go by
- Tag names do **NOT** have to be unique
- Tag names are **NOT** limited to specific characters
- Tags can have **aliases**, a.k.a. alternate names to go by

### Name

Expand Down Expand Up @@ -66,7 +66,7 @@ Lastly, when searching your files with broader categories such as `Character` or

<!-- prettier-ignore -->
!!! warning ""
**_Coming in version 9.6.x_**
**_Coming in version 9.6.x_**

Component tags will be built from a composition-based, or "HAS" type relationship between tags. This takes care of instances where an attribute may "have" another attribute, but doesn't inherit from it. Shrek may be an `Ogre`, he may be a `Character`, but he is NOT a `Leather Vest` - even if he's commonly seen _with_ it. Component tags, along with the upcoming "Tag Override" feature, are built to handle these cases in a way that still simplifies the tagging process without adding too much undue complexity for the user.

Expand All @@ -88,20 +88,22 @@ Custom palettes and colors can be created via the [Tag Color Manager](colors.md)

<!-- prettier-ignore -->
!!! warning ""
**_Coming in version 9.6.x_**
**_Coming in version 9.6.x_**

## Tag Properties

Properties are special attributes of tags that change their behavior in some way.

#### Is Category

The "Is Category" property of tags determines if a tag should be treated as a category itself when being organized inside the preview panel. If this tag or any tags inheriting from this tag (i.e. tags that have this tag as a "[Parent Tag](#parent-tags)"), then these tags will appear under a separated group that's named after this tag. Tags inheriting from multiple "category tags" will still show up under any applicable category.
The "Is Category" property of tags determines if a tag should be treated as a category itself when being organized inside the preview panel. If this tag or any tags inheriting from this tag (i.e. tags that have this tag as a "[Parent Tag](#parent-tags)"), then these tags will appear under a separated group that's named after this tag. By default, tags inheriting from multiple "category tags" will still show up under any applicable category.

This means that duplicates of tags can appear on entries if the tag inherits from multiple parent categories, however this is by design and reflects the nature of multiple inheritance. Any tags not inheriting from a category tag will simply show under a default "Tag" section.

![Tag Category Example](assets/tag_categories_example.png)

If you don't want a tag to appear in one, more, or even all the applicable categories, simply uncheck the category in the "Edit Tag" panel.
Copy link
Copy Markdown
Contributor Author

@Sola-ris Sola-ris Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I Haven't added an example image, since it would look inconsistent, with all the other ones being taken on macOS which I don't have access to


### Built-In Tags and Categories

The built-in tags "Favorite" and "Archived" inherit from the built-in "Meta Tags" category which is marked as a category by default. This behavior of default tags can be fully customized by disabling the category option and/or by adding/removing the tags' Parent Tags.
Expand All @@ -114,7 +116,7 @@ Due to the nature of how tags and Tag Felids operated prior to v9.5, the organiz

<!-- prettier-ignore -->
!!! warning ""
**_Coming in version 9.6.x_**
**_Coming in version 9.6.x_**

When the "Is Hidden" property is checked, any file entries tagged with this tag will not show up in searches by default. This property comes by default with the built-in "Archived" tag.

Expand All @@ -123,7 +125,7 @@ When the "Is Hidden" property is checked, any file entries tagged with this tag
The following are examples of how a set of given tags will respond to various search queries.

| Tag | Name | Shorthand | Aliases | Parent Tags |
| ------------------- | ------------------- | --------- | ---------------------- | -------------------------------------------- |
|---------------------|---------------------|-----------|------------------------|----------------------------------------------|
| _League of Legends_ | "League of Legends" | "LoL" | ["League"] | ["Game", "Fantasy"] |
| _Arcane_ | "Arcane" | "" | [] | ["League of Legends", "Cartoon"] |
| _Jinx (LoL)_ | "Jinx Piltover" | "Jinx" | ["Jinxy", "Jinxy Poo"] | ["League of Legends", "Arcane", "Character"] |
Expand All @@ -133,15 +135,15 @@ The following are examples of how a set of given tags will respond to various se
**The query "Arcane" will display results tagged with:**

| Tag | Cause of Inclusion | Tag Tree Lineage |
| --------------- | -------------------------------- | -------------------------- |
|-----------------|----------------------------------|----------------------------|
| Arcane | Direct match of tag name | "Arcane" |
| Jinx (LoL) | Search term is set as parent tag | "Jinx (LoL) > Arcane" |
| Zander (Arcane) | Search term is set as parent tag | "Zander (Arcane) > Arcane" |

**The query "League of Legends" will display results tagged with:**

| Tag | Cause of Inclusion | Tag Tree Lineage |
| ----------------- | ------------------------------------------------------ | ---------------------------------------------- |
|-------------------|--------------------------------------------------------|------------------------------------------------|
| League of Legends | Direct match of tag name | "League of Legends" |
| Arcane | Search term is set as parent tag | "Arcane > League of Legends" |
| Jinx (LoL) | Search term is set as parent tag | "Jinx (LoL) > League of Legends" |
Expand Down
4 changes: 2 additions & 2 deletions src/tagstudio/core/library/alchemy/constants.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@
DB_VERSION_LEGACY_KEY: str = "DB_VERSION"
DB_VERSION_CURRENT_KEY: str = "CURRENT"
DB_VERSION_INITIAL_KEY: str = "INITIAL"
DB_VERSION: int = 103
DB_VERSION: int = 104

TAG_CHILDREN_QUERY = text("""
WITH RECURSIVE ChildTags AS (
SELECT :tag_id AS tag_id
UNION
SELECT tp.child_id AS tag_id
FROM tag_parents tp
FROM tag_parents tp
INNER JOIN ChildTags c ON tp.parent_id = c.tag_id
)
SELECT * FROM ChildTags;
Expand Down
7 changes: 7 additions & 0 deletions src/tagstudio/core/library/alchemy/joins.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,10 @@ class TagEntry(Base):

tag_id: Mapped[int] = mapped_column(ForeignKey("tags.id"), primary_key=True)
entry_id: Mapped[int] = mapped_column(ForeignKey("entries.id"), primary_key=True)


class CategoryExclusion(Base):
__tablename__ = "category_exclusions"

tag_id: Mapped[int] = mapped_column(ForeignKey("tags.id"), primary_key=True)
category_id: Mapped[int] = mapped_column(ForeignKey("tags.id"), primary_key=True)
Loading
Loading