Skip to content

usage.md

Latest commit

 

History

History
87 lines (55 loc) · 6.37 KB

usage.md

File metadata and controls

87 lines (55 loc) · 6.37 KB
title Basic Usage
icon material/mouse

:material-mouse: Basic Usage

:material-database-plus: 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.

:material-database-refresh: 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).

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

Adding Tags to File Entries

Access the "Add Tag" search box by either clicking on the "Add Tag" button at the bottom of the right sidebar, accessing the "Add Tags to Selected" option from the File menu, or by pressing Ctrl+Shift+T.

From here you can search for existing tags or create a new one if the one you're looking for doesn't exist. Click the "+" button next to any tags you want to the currently selected file entries. To quickly add the top result, press the Enter/Return key to add the topmost tag and reset the tag search. Press Enter/Return once more to close the dialog box. By using this method, you can quickly add various tags in quick succession just by using the keyboard!

To remove a tag from a file entry, hover over the tag in the preview panel and click on the "-" icon that appears.

Adding Metadata to File Entries

To add a metadata field to a file entry, start by clicking the "Add Field" button at the bottom of the preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry

Editing Metadata Fields

Text Line / Text Box

Hover over the field and click the pencil icon. From there, add or edit text in the dialog box popup.

Creating Tags

Create a new tag by accessing the "New Tag" option from the Edit menu or by pressing Ctrl+T. In the tag creation panel, enter a tag name, optional shorthand name, optional tag aliases, optional parent tags, and an optional color.

  • The tag name is the base name of the tag. This does NOT have to be unique!
  • The tag shorthand is a special type of alias that displays in situations where screen space is more valuable, notably with name disambiguation.
  • Aliases are alternate names for a tag. These let you search for terms other than the exact tag name in order to find the tag again.
  • Parent Tags are tags in which this tag can substitute for in searches. In other words, tags under this section are parents of this tag.
    • Parent tags with the disambiguation check next to them will be used to help disambiguate tag names that may not be unique.
    • For example: If you had a tag for "Freddy Fazbear", you might add "Five Nights at Freddy's" as one of the parent tags. If the disambiguation box is checked next to "Five Nights at Freddy's" parent tag, then the tag "Freddy Fazbear" will display as "Freddy Fazbear (Five Nights at Freddy's)". Furthermore, if the "Five Nights at Freddy's" tag has a shorthand like "FNAF", then the "Freddy Fazbear" tag will display as "Freddy Fazbear (FNAF)".
  • The color option lets you select an optional color palette to use for your tag.
  • The "Is Category" property lets you treat this tag as a category under which itself and any child tags inheriting from it will be sorted by inside the preview panel.

Tag Manager

You can manage your library of tags by opening the "Tag Manager" panel from Edit -> "Manage Tags". From here you can create, search for, edit, and permanently delete any tags you've created in your library.

Editing Tags

To edit a tag, click on it inside the preview panel or right-click the tag and select "Edit Tag" from the context menu.

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.

Saving the Library

As of version 9.5, libraries are saved automatically as you go. To save a backup of your library, select File -> Save Library Backup from the menu bar.

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.