Overview¶
Tags¶
Once folders have been created, the mapping between those folders and the Shotgun entities from which they originated are maintained via tags. These tags exist within .sgfs.yml
files within the top-level of the directory that corresponds to the given entity.
Location¶
With the WesternX structure, the project tree (including tags) looks roughly like:
The_Awesome_Project/
.sgfs.yml # Project tag.
.sgfs-cache.sqlite # Reverse cache.
SEQ/
AA/
.sgfs.yml # "AA" Sequence tag.
AA_001_001/
.sgfs.yml # "AA_001_001" Shot tag.
Light/
.sgfs.yml # Tags for Tasks with step code "Light".
Assets/
Character/
Cow/
.sgfs.yml # "Cow" Asset tag.
Model/
.sgfs.yml # "Tags for Tasks with step code "Model".
Contents¶
The .sgfs.yml
files are YAML documents containing a logical document for each tag. Those documents are mappings including a timestamp, the entity for that tag, and other arbitrary metadata. The entities have been dumped with all the information that was known about their lineage up to the project. For example, a tag for a shot may look like:
---
created_at: 2012-10-23 18:27:24.312373
entity:
code: RG_006_001
id: 5847
project:
id: 70
name: Super Buddies
type: Project
updated_at: 2012-09-17 22:40:23
sg_sequence:
code: RG
id: 107
name: RG
project:
id: 70
type: Project
type: Sequence
updated_at: 2012-10-23 19:29:58
type: Shot
updated_at: 2012-10-24 01:31:37
Rules¶
Usage of tags follows a few general rules:
- tags must contain an entity;
- tags may optionally contain metadata in addition to that entity;
- a directory may be tagged multiple times with different entities;
- if a directory is tagged more than once with the same entity, only the most recent tag will be returned and older metadata will be lost (although older Shotgun data will be merged into the session if not outdated).
The Path Cache¶
While tags create a link from directories to their corresponding entities, the path cache maintains the links from entities to directories in which they are tagged.
The path cache is implemented as a sqlite3 database located at .sgfs/cache.sqlite
within each project, and accessible via the PathCache
API.
Since the data in the path cache and tags is redundant, the path cache should be treated as a derivative of the tags and may be reconstructed from the tags at any time via the sgfs-relink command.
Caveats or Known Issues¶
Projects must be tagged manually in order for other tools to be able to create structures within them (by default). This is partially a technical restriction (for the creation of the path cache, but also for safety. Manual tagging is done via the sgfs-tag command:
sgfs-tag Project 1234 path/to/project
Contexts, Schemas, and Structures¶
The Context
, Schema
, and Structure
are three different (but related) directed acyclic graphs used in the construction of file structures on disk.
A Context
represents a set of Shotgun entities and their relationships.
A Schema
represents a template for file structures, and is defined via template structures and YAML files describing them.
A Structure
is the specific directories and files that should exist for a set of entities, and allows for creation or inspection of those structures. It is created by rendering Schema for a given Context.