Basic Usage¶

Creating/Opening a Library¶

To create or open a library, go to File -> Open/Create Library in the menu bar or use Ctrl+O (⌘ Command +O on macOS) and chose a folder with file contents you'd like to use as a TagStudio library. If a .TagStudio folder doesn't already exist inside the directory, TagStudio will create one and automatically scan the folder for files to include. Otherwise, the pre-existing library is opened.

Refreshing Directories¶

TagStudio automatically scans for new or updated files when opening a library by default. Manually refresh by going to File -> Refresh Directories in the menu or by using Ctrl+R (⌘ Command +R on macOS).

TagStudio Libraries

To learn more about how TagStudio libraries work and how to use them, visit the Libraries page.

Tagging¶

With one or more file entries selected, you can search for or create a new tag by clicking the "Add Tag" button at the bottom of the preview panel or by pressing Ctrl+T.

This will open the the "Tag Bar", a combination search/creation bar that is designed to allow you to quickly create and apply tags that don't exist yet, find and apply existing tags in your library, and verify if certain tags already exist and/or are applied to your selection.

Every step is keyboard-friendly, allowing for an efficient tagging "flow state" when it comes to creating and applying tags.

Classic Tag Search Panel

You can access the classic tag search panel by going to File -> Add Tag to Selected in the menu bar, or by pressing Shift+Ctrl+T. Note that this panel will change and move in the future, becoming part of a set of dockable side-panels for tagging that can stay open between making selections. See the roadmap for more info.

Tag Bar: Creating Tags¶

Type to search for an existing tag, or use that search term to quickly create and apply a new tag to your selection. Pressing Enter with no results will create a tag from your search query and apply it to the selected entries.

After applying a tag, the "Add Tag" button is now focused, allowing you to press Enter or Space to quickly reactivate the bar. Alternatively, you may edit your new tag by right-clicking the tag and selecting "Edit".

Tags can be also viewed, created, edited, or deleted from the Edit -> Manage Tags window.

Optionally Always Edit New Tags

If you prefer opening an "Edit" window for tags after creating them and before they get applied to your selection, you can toggle this option on by right-clicking the search bar and clicking "Edit After Creating a New Tag", or by visiting the same setting in the Settings window. By default, this option is off.

Tag Bar: Searching for Tags¶

Pressing Enter with one or more results will apply the first tag to your selection (assuming it's not already on your selection).

Tags that are already present on your entries will be greyed out and ignored when pressing Enter. This lets you visually confirm that a tag already exists and has been applied to the selection.

Force Create Tag¶

Holding Shift while pressing Enter will force create a tag from the search bar text, regardless of the results. This is indicated by the first tag in the results becoming greyed out. This is especially useful when you need to create a new tag with a name that partially overlaps with an existing tag's name.

Creating and Adding Fields¶

Fields are extra pieces of information you can add to file entries, such as titles, comments, notes, specific dates or times. Unlike tags, fields are based on templates that contain pre-filled information such as the field type and title, and that information is copied to fields when adding them to entries. Editing field information on entries does not modify the template it was created from.

Creating and adding fields to entries is extremely similar to how it works for tags, with a few notable differences:

Click "Add Field" or press Ctrl+L to open the field bar.
The same template can by applied to an entry any number of times.
New field templates are automatically edited after being created, since they have a type that must be chosen before they can be used.
- This is separate from the option to automatically edit a field's contents once a field has been added to an entry
Editing a field's contents immediately after it's added to an entry is enabled by default, and can be toggled by right-clicking the search bar and clicking "Edit After Adding a Field", or by visiting the same setting in the Settings window.

Relinking Moved Files¶

Inevitably some of the files inside your library will be renamed, moved, or deleted. If a file has been renamed or moved, TagStudio will display the thumbnail as a red broken chain link. To relink moved files or delete these entries, select the "Manage Unlinked Entries" option under the Tools menu. Click the "Refresh" button to scan your library for unlinked entries. Once complete, you can attempt to "Search & Relink" any unlinked file entries to their respective files, or "Delete Unlinked Entries" in the event the original files have been deleted and you no longer wish to keep their entries inside your library.

Warning

There is currently no method to relink entries to files that have been renamed - only moved or deleted. This is a high priority for future releases.

Warning

If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are high priorities for future versions.

Launch Arguments¶

There are a handful of launch arguments you can pass to TagStudio via the command line or a desktop shortcut.

Argument	Short	Description
`--cache-file <path>`	`-c`	Path to a TagStudio .ini or .plist cache file to use.
`--open <path>`	`-o`	Path to a TagStudio Library folder to open on start.
`--settings-file <path>`	`-s`	Path to a TagStudio .toml global settings file to use.
`--version`	`-v`	Displays TagStudio version information.