Common Thorg Workspace Patterns
Main patterns for workspaces
Pattern 1: Main workspace - At Home (Recommended to start with)
This is the recommended pattern to start with as it's the simplest to set up and preserves your Git history as you move notes between vaults.
In this pattern, you have a single Git repository for your workspace containing one private vault. This means you only have one Git repository to manage initially. You can create additional vaults under the workspace, and they'll be source controlled as well. Git history is retained as you move files between vaults, provided the vaults are part of this workspace's repository and you commit moves separately from content changes (so Git can detect file similarity).
Pattern 2: Main Workspace — At Home - Public Repo as Separate Vault
Your main $THORG_WORKSPACE contains a private vault in one Git repository (accessible only to you) and a public vault published as a webview in a separate Git repository.
- PRO: Separate repository for public vault that is ready to be shared as GIT repository.
- CON: Moving notes from public to private looses their edit GIT history as the repositories are separate.
Pattern 3: Main Workspace — At Work
Your main Thorg Workspace contains two vaults:
- A private vault that only you can access
- A team vault stored in a separate Git repository, synced and shared among teammates, and published as a webview for the company.
In this pattern your workspace can also pull in multiple team vaults under your workspace if you kept separate vaults per project documentation along with code. (See Thorg Workspace Pattern Along with Code).
To make it easy for teammates to pull in multiple repositories that represents vaults under a single workspace you can setup Thorg Workspace to use Git Submodule for the vaults that it tracks, and expect a symlink for private vault (since each teammate could have their own private vault that only they can access).
Pattern 4: Workspace Along with code
In this pattern, your Thorg Workspace lives in the same directory as your code (most aligned with monorepo code workflow). This tightly integrates documentation notes with the repos Git history. However, Even in this case it's recommended to keep your vault as a separate git repository and to use Git Submodule for your vault.
Separating the vault as its own git repository while keeping the history synced up through Git Submodule makes it possible to combine the vault with other vaults in a different thorg workspace (see Thorg Workspace pattern With Team Vault).
Optional Add-on Patterns (Intermediate/Advanced)
These patterns are optional and can be combined with the setups above.
Add-on Pattern 1: Git Submodule for Assets
Why: Keeps your main repository's Git history clean by separating out images and other assets.
How: Create a separate Git repository for each vault's assets (e.g., a private vault would have a corresponding private-assets repository). Then add this repository as a submodule at $VAULT/assets/submodule. See How to Add GIT Submodule for details.
Pros:
- Keeps Git histories separate while maintaining a clear relationship between repositories
- Allows you to track exactly which asset commits correspond to which main repository commits
Cons:
- Adds complexity to your workflow
- Requires familiarity with Git submodule commands
Children
Backlinks