mirror of
https://github.com/TagStudioDev/TagStudio.git
synced 2026-09-11 21:30:51 +02:00
docs: update library sync documentation
This commit is contained in:
Travis Abendshien
Binary file not shown.
|
Before Width: | Height: | Size: 49 KiB After Width: | Height: | Size: 58 KiB |
+59
-4
@@ -33,13 +33,68 @@ To create or open a [library](libraries.md), go to **File -> Open/Create Library
|
||||
!!! info "Legacy Library Migration"
|
||||
If you open a library created with TagStudio **v9.4.2 or earlier** in **[v9.5.0](changelog.md#950-march-3rd-2025) or later**, you'll be walked through a migration process that converts the old `ts_library.json` save file to the new `ts_library.sqlite` format. The original JSON file is preserved and can be easily deleted from the **View -> Library Information** panel once you're satisfied with the migration.
|
||||
|
||||
## :material-database-refresh: Refreshing Directories
|
||||
## :material-database-sync: Library Syncing
|
||||
|
||||
TagStudio automatically scans for new or updated files when opening a library by default. This behavior can be toggled in the settings if your library is very large and/or located on a slow drive.
|
||||
A TagStudio library gets synced with the files found in your chosen content folders and certain metadata attributes (e.g. stats) found on those files. This is a **non-destructive, read-only** process and none of your content files are moved, modified, or deleted. Syncing is indicated by a temporary progress bar, and you can continue to use TagStudio normally while syncing occurs.
|
||||
|
||||
|
||||
Syncing automatically occurs when you open a library by default, and you can manually sync a library at any time by going to **File -> Sync Library** in the menubar to by pressing <kbd>Ctrl</kbd>+<kbd>R</kbd> (<kbd>⌘ Command </kbd>+<kbd>R</kbd> on macOS). If you do not wish for your library to be synced when opened, you can disable this behavior in the settings.
|
||||
|
||||
To manually refresh your library at any time, use **File -> Refresh Directories** from the menu or by using <kbd>Ctrl</kbd>+<kbd>R</kbd> (<kbd>⌘ Command </kbd>+<kbd>R</kbd> on macOS).
|
||||
<figure markdown="span">
|
||||
|
||||
<figcaption>
|
||||
Settings -> Sync Library on Open
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
### :material-link-variant: Automatic Relinking
|
||||
|
||||
Unlinked entries are file entries in your TagStudio library that have become "unlinked" from their original file on disk, likely as a result of the original file being renamed, moved, or deleted. TagStudio attempts to automatically relink any of these entries as a part of the syncing process, but there are some scenarios where automatic relinking is not possible or too ambiguous and requires a manual review. Below is a complete table of every scenario in which file entries can become unlinked, and whether or not TagStudio can auto-relink them:
|
||||
|
||||
| Case | File Moved? | File Renamed? | File Modified? | Unlinked Entries | Matched Files | Auto-Relink |
|
||||
| -------: | :---------: | :-----------: | :------------: | :--------------: | :-----------: | :---------------------------------: |
|
||||
| **\#0** | _No_ | _No_ | **Yes** | 0 | — | :material-minus-circle:{.lg .gray} |
|
||||
| **\#1** | — | — | — | 1 | 0 | :material-close-circle:{.lg .red} |
|
||||
| **\#2** | **Yes** | **Yes** | **Yes** | 1 | 0 | :material-close-circle:{.lg .red} |
|
||||
| **\#3** | **Yes** | **Yes** | _No_ | 1 | 1 | :material-check-circle:{.lg .green} |
|
||||
| **\#4** | **Yes** | **Yes** | _No_ | 1 | 2+ | :material-close-circle:{.lg .red} |
|
||||
| **\#5** | **Yes** | **Yes** | _No_ | 2+ | Any | :material-close-circle:{.lg .red} |
|
||||
| **\#6** | **Yes** | _No_ | **Yes** | 1 | 1 | :material-check-circle:{.lg .green} |
|
||||
| **\#7** | **Yes** | _No_ | _No_ | 1 | 1 | :material-check-circle:{.lg .green} |
|
||||
| **\#8** | **Yes** | _No_ | _No_ | 1 | 2+ | :material-close-circle:{.lg .red} |
|
||||
| **\#9** | **Yes** | _No_ | _No_ | 2+ | Any | :material-close-circle:{.lg .red} |
|
||||
| **\#10** | _No_ | **Yes** | **Yes** | 1 | 0 | :material-close-circle:{.lg .red} |
|
||||
| **\#11** | _No_ | **Yes** | _No_ | 1 | 1 | :material-check-circle:{.lg .green} |
|
||||
| **\#12** | _No_ | **Yes** | _No_ | 1 | 2+ | :material-close-circle:{.lg .red} |
|
||||
| **\#13** | _No_ | **Yes** | _No_ | 2+ | Any | :material-close-circle:{.lg .red} |
|
||||
|
||||
#### Explanations
|
||||
|
||||
- **Case \#0**: _Modifying file content alone does not create unlinked entries._
|
||||
- **Case \#1**: If the original file was deleted, no matches will be found. TagStudio leaves the decision to delete entries up to the user.
|
||||
- **Case \#2**: If the original file bears no similarities to the unlinked entry anymore, it is indistinguishable from a deleted or new file.
|
||||
- **Case \#3**: The file has been moved and renamed with a high degree of confidence.
|
||||
- **Case \#4**: If more than one file is matched with the same stats, the case is too ambiguous.
|
||||
- **Case \#5**: If two or more entries share the same stats, it's not clear which entry a matched file belongs to.
|
||||
- **Case \#6**: The file has been moved and modified, but since no other file shares its filename, it is assumed to be the same file with a decent degree of confidence.
|
||||
- **Case \#7**: The original file has been moved with a high degree of confidence.
|
||||
- **Case \#8**: If multiple copies of the same moved file are matched in different locations, the case is ambiguous.
|
||||
- **Case \#9**: _Similar to **\#5**._ If two or more entries share the same filename and stats, it's not clear which entry a matched file belongs to.
|
||||
- **Case \#10**: _Same as **\#2**._
|
||||
- **Case \#11**: The file has been renamed with a high degree of confidence.
|
||||
- **Case \#12**: _Same as **\#4**._
|
||||
- **Case \#13**: _Same as **\#5**._
|
||||
|
||||
Every numbered case above assumes the entry has saved file metadata attributes to help match against (added in **v9.7**), in which case the **file modification date** combined with the **file size** is used as a soft file signature to aid in scenarios such as renames or moves. If no file metadata is stored with the file entry, or if this soft file signature doesn't lead to a confident match, TagStudio falls back to matching by filename alone: a single file found with that name is automatically relinked, while zero or multiple filename matches leave the entry unlinked for manual review.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! warning
|
||||
There's currently no way to manually specify which remaining unlinked entries should be linked with which files, only to delete the entries from the library. Manual relinking is a high priority feature for future releases.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! warning "Switching from a Case-Sensitive to Case-Insensitive Filesystem (i.e. Windows)"
|
||||
If you switch from using TagStudio on a computer with a case-sensitive filesystem to one with a *case-insensitive* one, TagStudio will treat any entries added up to this point with the same filepath + name under case-insensitivity as duplicate entries and merge them. The automatic relinking process will also take case-insensitivity into account when relinking entries.
|
||||
|
||||
Currently, TagStudio only uses this case-insensitivity mode when running on Windows. Future versions will be more precise about this distinction, with the aim of determining the case sensitivity on a per-drive basis.
|
||||
|
||||
## :material-database-cog: Library Information Panel
|
||||
|
||||
|
||||
+11
-11
@@ -96,7 +96,7 @@ A detailed specification written for the TagStudio tag and/or library format. In
|
||||
- [x] Delete Old Backups **[[v9.5.4](changelog.md#954-september-1st-2025)]**
|
||||
- [x] Delete Legacy JSON File **[[v9.5.4](changelog.md#954-september-1st-2025)]**
|
||||
- [x] Translations
|
||||
- [ ] Search Bar Rework :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
|
||||
- [ ] Search Bar Rework :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
|
||||
- [ ] Improved Tag Autocomplete :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Tags appear as widgets in search bar _(similar to new tag search/create bar)_ :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Unified Media Player
|
||||
@@ -136,7 +136,7 @@ A detailed specification written for the TagStudio tag and/or library format. In
|
||||
- [x] Theme
|
||||
- [x] Thumbnail Generation **[[v9.5.4](changelog.md#954-september-1st-2025)]**
|
||||
- [x] Configurable Page Size
|
||||
- [ ] Library Settings :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
|
||||
- [ ] Library Settings :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
|
||||
- [ ] Stored in `.TagStudio` folder :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Toggle File Extension Label :material-chevron-double-up:{ .priority-med title="Medium Priority" }
|
||||
- [ ] Toggle Duration Label :material-chevron-double-up:{ .priority-med title="Medium Priority" }
|
||||
@@ -149,13 +149,13 @@ A detailed specification written for the TagStudio tag and/or library format. In
|
||||
|
||||
- [x] Per-Library Tags
|
||||
- [ ] Global Tags :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.8.x]**
|
||||
- [ ] Multiple Root Directories :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
|
||||
- [ ] Ability to store TagStudio data folder separate from library content folder(s) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
|
||||
- [ ] Automatic Entry Relinking :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.8.x]**
|
||||
- [ ] Detect Renames :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Detect Moves :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Detect Deletions :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Performant :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Multiple Root Directories :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
|
||||
- [ ] Ability to store TagStudio data folder separate from library content folder(s) :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
|
||||
- [x] Automatic Entry Relinking :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.0]**
|
||||
- [x] Detect Renames :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Detect Moves :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Some way to safely handle unlinked entries presumed to be from deleted files automatically (deleted after X days?) :material-chevron-double-up:{ .priority-med title="Medium Priority" }
|
||||
- [x] Performant :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Background File Scanning :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Thumbnail Caching **[[v9.5.0](changelog.md#950-march-3rd-2025)]**
|
||||
- [ ] Audio Waveform Caching :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.7.x]**
|
||||
@@ -166,7 +166,7 @@ A detailed specification written for the TagStudio tag and/or library format. In
|
||||
File or file-like [entries](entries.md) stored in the library.
|
||||
|
||||
- [x] File Entries **[v1.0.0]**
|
||||
- [ ] URL Entries / Bookmarks :material-chevron-up:{ .priority-low title="Low Priority" } **[v9.6.x]**
|
||||
- [ ] URL Entries / Bookmarks :material-chevron-up:{ .priority-low title="Low Priority" } **[v9.8.x]**
|
||||
- [x] Fields
|
||||
- [x] Text Lines
|
||||
- [x] Text Boxes
|
||||
@@ -267,7 +267,7 @@ Discrete library objects representing [attributes](<https://en.wikipedia.org/wik
|
||||
Sharable TagStudio library data in the form of data packs (tags, colors, etc.) or other formats.
|
||||
Packs are intended as an easy way to import and export specific data between libraries and users, while export-only formats are intended to be imported by other programs.
|
||||
|
||||
- [ ] Color Packs :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.x]**
|
||||
- [ ] Color Packs :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.7.x]**
|
||||
- [ ] Importable
|
||||
- [ ] Exportable
|
||||
- [x] UUIDs + Namespaces :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
|
||||
@@ -80,6 +80,7 @@ img {
|
||||
th,
|
||||
td {
|
||||
padding: 0.5em 1em 0.5em 1em !important;
|
||||
min-width: 0 !important;
|
||||
}
|
||||
|
||||
hr {
|
||||
|
||||
+6
-16
@@ -12,9 +12,13 @@ icon: material/mouse
|
||||
|
||||
To create or open a [library](libraries.md), go to **File -> Open/Create Library** in the menu bar or use <kbd>Ctrl</kbd>+<kbd>O</kbd> (<kbd>⌘ Command </kbd>+<kbd>O</kbd> 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
|
||||
### :material-database-sync: Library Syncing
|
||||
|
||||
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 <kbd>Ctrl</kbd>+<kbd>R</kbd> (<kbd>⌘ Command </kbd>+<kbd>R</kbd> on macOS).
|
||||
A TagStudio library gets synced with the files found in your content folders. This is a **non-destructive, read-only** process and none of your files are moved, modified, or deleted. Syncing is indicated by a temporary progress bar, and you can continue to use TagStudio normally while syncing occurs.
|
||||
|
||||
### :material-link-variant: Automatic Relinking
|
||||
|
||||
Files that become moved, renamed, or modified will try to be automatically relinked during syncing. If a file cannot be found or a match cannot be safely made, it will stay unlinked until the entries are manually deleted under "Fix Unlinked Entries". _Manual relinking is a high priority feature for future versions._
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! abstract "TagStudio Libraries"
|
||||
@@ -115,20 +119,6 @@ Creating and adding fields to entries is extremely similar to how [tagging](#tag
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! 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.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! 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.
|
||||
|
||||
Reference in New Issue
Block a user