Tiny-Home/Tiny-Lab
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import

Browse Source
This commit is contained in:
Admin
2026-07-11 17:08:37 +00:00
commit 03e5f3452b
303 changed files with 43365 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Local/storage/thlab-notes/worker/docs/cli/build.md
+78
View File
@@ -0,0 +1,78 @@
---
title: quartz build
aliases:
- build
---
The `build` command transforms your Markdown content into a static HTML website. It processes your files through the configured plugins and outputs the final site to a directory of your choice.
## Flags
| Flag | Shorthand | Description | Default |
| ----------------- | --------- | --------------------------------------------------------- | ----------------- |
| `--directory` | `-d` | The directory containing your Quartz project | Current directory |
| `--verbose` | `-v` | Enable detailed logging for debugging | `false` |
| `--output` | `-o` | The directory where the built site will be saved | `public` |
| `--serve` | | Start a local development server | `false` |
| `--watch` | | Rebuild the site when files change | `false` |
| `--port` | | The port for the development server | `8080` |
| `--wsPort` | | The port for the WebSocket hot-reload server | `3001` |
| `--baseDir` | | Set a base directory for the site (e.g. for GitHub Pages) | `/` |
| `--remoteDevHost` | | The hostname to use for the development server | `localhost` |
| `--bundleInfo` | | Output a JSON file with bundle size information | `false` |
| `--concurrency` | `-c` | Number of worker threads to use for building | CPU core count |
## Examples
### Basic Build
Generate your site into the `public` folder.
```shell
npx quartz build
```
### Development Mode
Start a local server and watch for changes. This is the most common way to preview your site while writing.
```shell
npx quartz build --serve
```
### Custom Output and Port
Build to a specific folder and run the server on a different port.
```shell
npx quartz build --serve --output dist --port 3000
```
### Performance Tuning
If you have a very large vault, you can limit the number of concurrent workers to save memory.
```shell
npx quartz build --concurrency 2
```
## Serve vs Watch
The `--serve` and `--watch` flags control different behaviors:
- **`--serve`** starts a local development server AND automatically watches for changes (implies `--watch`). This is the recommended mode for local development.
- **`--watch`** only watches for file changes and rebuilds automatically, without starting a server. This is useful for CI pipelines or custom server setups where you want automatic rebuilds but handle serving separately.
In most cases, you want `--serve`:
```shell
npx quartz build --serve
```
## Development Server
The `--serve` flag starts a local web server. This server is intended for development and previewing only. It is not designed for production use. For information on how to deploy your site, see [[hosting]].
### Hot Reloading
When running with `--serve`, Quartz automatically enables `--watch`. It uses a WebSocket connection (on the port specified by `--wsPort`) to notify your browser when a file has changed. The browser will then automatically refresh to show the latest version of your content.
Local/storage/thlab-notes/worker/docs/cli/create.md
+83
View File
@@ -0,0 +1,83 @@
---
title: quartz create
---
The `create` command initializes a new Quartz project. It helps you set up your content folder, choose a configuration template, set your site's base URL, and configure how Quartz should handle your Markdown files.
## Flags
| Flag | Shorthand | Description |
| ------------- | --------- | --------------------------------------------------------------------- |
| `--template` | `-t` | Configuration template (`default`, `obsidian`, `ttrpg`, or `blog`) |
| `--directory` | `-d` | The directory where Quartz will be initialized |
| `--source` | `-s` | The source directory of your Markdown files |
| `--strategy` | `-X` | How to handle the source files (`new`, `copy`, or `symlink`) |
| `--links` | `-l` | How to resolve internal links (`absolute`, `shortest`, or `relative`) |
| `--baseUrl` | `-b` | Base URL for your site (e.g. `mysite.github.io/quartz`) |
| `--verbose` | `-v` | Enable detailed logging |
## Templates
When you run `quartz create`, you can choose a configuration template that pre-configures Quartz for your use case. The selected template always overwrites `quartz.config.yaml`, even if one already exists. After applying the template, Quartz automatically runs plugin resolution to install any plugins the template requires and remove any that are no longer referenced.
- **Default**: A clean Quartz setup with sensible defaults. Best for starting from scratch.
- **Obsidian**: Optimized for Obsidian vaults with full Obsidian Flavored Markdown support (wikilinks, callouts, mermaid diagrams, etc.). Automatically sets link resolution to `shortest` and skips the link resolution prompt.
- **TTRPG**: Builds on the Obsidian template with the addition of the [Leaflet bases plugin](https://github.com/Requiae/quartz-leaflet-bases-plugin) and [ITS Theme](https://github.com/saberzero1/quartz-themes) (`its-theme.ttrpg-dnd`). Great for D&D and TTRPG wikis. Also skips the link resolution prompt.
- **Blog**: A blog-focused setup with [recent notes](https://github.com/quartz-community/recent-notes) enabled (showing the 5 most recent posts with tags) and [comments](https://github.com/quartz-community/comments) enabled via giscus. You'll need to fill in the `TODO:` placeholder values in `quartz.config.yaml` with your own giscus repository details.
## Base URL
During setup, Quartz will ask for the base URL of your site. This is the URL where your site will be deployed (e.g. `mysite.github.io/quartz`).
- Do **not** include the protocol (`https://`) — if you do, it will be automatically stripped.
- Trailing slashes are also removed automatically.
- See [[configuration]] for more details on how `baseUrl` is used.
## Strategies
When you run `quartz create`, you must choose a strategy for your content:
- **new**: Creates a fresh, empty content folder. Use this if you are starting a new project from scratch.
- **copy**: Copies all files from your source directory into the Quartz content folder. This is the safest option for existing vaults as it doesn't touch your original files.
- **symlink**: Creates a symbolic link from the Quartz content folder to your source directory. Any changes you make in your source directory (e.g. in Obsidian) will be immediately reflected in Quartz.
## Link Resolution
Quartz needs to know how to interpret the internal links in your Markdown files:
- **shortest**: Resolves links to the closest matching file name. This is the default for Obsidian.
- **absolute**: Resolves links relative to the root of your content folder.
- **relative**: Resolves links relative to the current file's location.
> [!note]
> When using the **Obsidian** or **TTRPG** templates, link resolution is automatically set to `shortest` and the prompt is skipped.
## Interactive Walkthrough
If you run `npx quartz create` without any arguments, it will guide you through an interactive setup:
1. **Choose a template**: Select a configuration template (`Default`, `Obsidian`, `TTRPG`, or `Blog`).
2. **Select a strategy**: Choose between `new`, `copy`, or `symlink`.
3. **Enter base URL**: Provide the URL where your site will be hosted.
4. **Select link resolution**: Choose how your links are formatted (skipped for Obsidian and TTRPG templates).
5. **Finish**: Quartz will set up the directory structure, create your configuration, and automatically install any plugins referenced in the template.
## Example: Importing an Obsidian Vault
To create a Quartz project that links directly to an existing Obsidian vault:
```shell
npx quartz create --template obsidian --strategy symlink --source ~/Documents/MyVault
```
This command tells Quartz to use the Obsidian template (with full OFM support and shortest link resolution), look at your vault in `~/Documents/MyVault`, and use symbolic links so changes are synced.
## Example: Setting Up a Blog
To quickly set up a blog with recent notes and comments:
```shell
npx quartz create --template blog --strategy new --baseUrl myblog.github.io
```
After setup, edit `quartz.config.yaml` to fill in your giscus repository details in the comments plugin section.
Local/storage/thlab-notes/worker/docs/cli/index.md
+55
View File
@@ -0,0 +1,55 @@
---
title: CLI Reference
---
The Quartz CLI is the primary way to interact with your Quartz project. It provides commands for creating new projects, building static sites, syncing with GitHub, and managing plugins.
You can run the CLI using `npx quartz`.
## Quick Reference
| Command | Description | Example |
| --------- | ------------------------------------------------------- | ------------------------ |
| `create` | Initialize a new Quartz project with template selection | `npx quartz create` |
| `build` | Generate static HTML files | `npx quartz build` |
| `sync` | Sync content with GitHub | `npx quartz sync` |
| `upgrade` | Upgrade Quartz to the latest version (alias: `update`) | `npx quartz upgrade` |
| `plugin` | Manage Quartz plugins (install, add, remove, etc.) | `npx quartz plugin list` |
| `tui` | Launch the interactive plugin manager | `npx quartz tui` |
## Commands
- [[create|create]]: Initialize a new Quartz project with a choice of templates (default, obsidian, ttrpg, blog) and base URL configuration.
- [[build|build]]: Build your Quartz site into static HTML. Includes a development server.
- [[sync|sync]]: Push and pull changes between your local machine and GitHub.
- [[upgrade|upgrade]]: Upgrade the Quartz framework to the latest version. Also available as `npx quartz update`.
- [[restore|restore]]: Recover your content folder from the local cache.
- [[cli/plugin|plugin]]: Install, add, remove, prune, and configure plugins. Use `plugin install` with flags for lockfile/config sync, updates, and checks.
- [[tui|tui]]: Use a terminal interface to manage plugins and layout.
## Global Flags
These flags are accepted by every Quartz command:
| Flag | Shorthand | Description | Default |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------- | -------------- |
| `--directory` | `-d` | The directory containing your Quartz project | `content` |
| `--verbose` | `-v` | Enable detailed logging for debugging | `false` |
| `--concurrency` | `-c` | Max parallel workers for operations that run in parallel (e.g. `build`, `plugin install`, `plugin add`) | CPU core count |
Commands that don't perform parallel work accept `-c` as a no-op, so it's always safe to pass. See [[build#Performance Tuning|build]] and [[cli/plugin#Installing on low-end hardware|plugin]] for practical examples.
## Help and Versioning
To see a full list of available flags for any command, use the `--help` flag.
```shell
npx quartz --help
npx quartz build --help
```
To check which version of Quartz you are currently running, use the `--version` flag.
```shell
npx quartz --version
```
Local/storage/thlab-notes/worker/docs/cli/plugin.md
+281
View File
@@ -0,0 +1,281 @@
---
title: quartz plugin
---
The `plugin` command is the heart of the Quartz v5 plugin management system. it allows you to install, configure, and update plugins directly from the command line.
All plugins are stored in the `.quartz/plugins/` directory, and their versions are tracked in `quartz.lock.json`.
## Subcommands
### list
List all currently installed plugins and their versions.
```shell
npx quartz plugin list
```
### add
Add a new plugin from a Git repository.
```shell
npx quartz plugin add github:username/repo
```
To install from a specific branch or ref, append `#ref` to the source:
```shell
npx quartz plugin add github:username/repo#my-branch
npx quartz plugin add git+https://github.com/username/repo.git#my-branch
npx quartz plugin add https://github.com/username/repo.git#my-branch
```
You can also add a plugin from a local directory. This is useful for local development or airgapped environments:
```shell
npx quartz plugin add ./path/to/my-plugin
npx quartz plugin add ../sibling-plugin
npx quartz plugin add /absolute/path/to/plugin
```
Local plugins are symlinked into `.quartz/plugins/`, so any changes you make to the source directory are reflected immediately without re-installing.
When a branch is specified, it is stored in the lockfile. All subsequent commands (`install`, `prune`) will respect that branch automatically. Use `install --latest` to fetch the latest commit from that branch.
> [!tip]
> `plugin add` also accepts `--concurrency` / `-c` to limit how many remote repositories are cloned and built at the same time. This is the same flag documented under [[#install]] and is useful when adding several plugins at once on low-end hardware.
### remove
Remove an installed plugin.
```shell
npx quartz plugin remove plugin-name
```
### install
Install plugins for your Quartz project. By default, this installs all plugins listed in your `quartz.lock.json` file.
```shell
npx quartz plugin install
```
#### Flags
- `--from-config`: Synchronize plugins with `quartz.config.yaml` instead of the lockfile. This will install missing plugins and prune orphaned ones.
- `--latest`: Fetch the latest version of plugins from their remote sources instead of using the version in the lockfile.
- `--clean`: Skip existing directories and perform a fresh installation.
- `--dry-run`: Preview the changes without actually installing or removing any files.
- `--concurrency`, `-c`: Maximum number of plugins to clone, fetch, and build in parallel. Defaults to the number of CPU cores. Lower this (e.g. `-c 1` or `-c 2`) on memory- or CPU-constrained machines where the default parallelism causes failures, OOMs, or hangs. See [[#Installing on low-end hardware]] below.
#### Positional Arguments
- `[names..]`: Optional list of specific plugin names to install or update.
```shell
# Update specific plugins to latest
npx quartz plugin install --latest plugin-a plugin-b
# Preview what would be installed from config
npx quartz plugin install --from-config --dry-run
```
### enable / disable
Toggle a plugin's status in your `quartz.config.yaml` without removing its files.
```shell
npx quartz plugin enable plugin-name
npx quartz plugin disable plugin-name
```
### config
View or modify the configuration for a specific plugin.
```shell
# View config
npx quartz plugin config plugin-name
# Set a value
npx quartz plugin config plugin-name --set key=value
```
### prune
Remove installed plugins that are no longer referenced in your `quartz.config.yaml`. This is useful for cleaning up after removing plugin entries from your configuration.
> [!note]
> Running `plugin install --from-config` also removes orphaned plugins as part of its synchronization. Use `prune` when you only want to clean up without installing anything new.
```shell
npx quartz plugin prune
```
Use `--dry-run` to preview which plugins would be removed without making changes:
```shell
npx quartz plugin prune --dry-run
```
## Common Workflows
### Adding and Enabling a Plugin
To add a new plugin and start using it:
1. Add the plugin: `npx quartz plugin add github:quartz-community/example`
2. Enable it: `npx quartz plugin enable example`
### Updating Everything
To keep your plugins fresh:
```shell
npx quartz plugin install --latest
```
### Installing on low-end hardware
By default, `plugin install` and `plugin add` clone, fetch, and build plugins in parallel across all your CPU cores. On memory-constrained machines (low-end laptops, Raspberry Pi, small VPS instances, restrictive CI runners) this can exhaust RAM or overwhelm the system because each worker may kick off its own `npm install` / `npm run build` at the same time.
> [!note]
> Most community plugins now ship with a pre-built `dist/` directory. When Quartz finds this, it skips the installation and build steps entirely, making the process much faster and lighter on resources. This section is primarily relevant for plugins in development or those that don't provide pre-built distribution.
If `plugin install` fails, hangs, or OOMs on your machine, lower the concurrency with `--concurrency` / `-c`:
```shell
# Install one plugin at a time (safest, slowest)
npx quartz plugin install --latest -c 1
# Two at a time — usually a good balance on 4 GB machines
npx quartz plugin install --latest --concurrency 2
```
The same flag works on `plugin add` and the other plugin subcommands that perform parallel work:
```shell
npx quartz plugin add github:quartz-community/some-plugin -c 1
```
### Managing Configuration
If you want to change a plugin setting without opening the YAML file:
```shell
npx quartz plugin config explorer --set useSavedState=true
```
### Cleaning Up Unused Plugins
If you've removed plugins from your config and want to clean up leftover files:
```shell
npx quartz plugin prune --dry-run # preview first
npx quartz plugin prune # remove orphaned plugins
```
### Setting Up from Config
When setting up on a new machine or in CI, `install --from-config` ensures your installed plugins match your config — installing missing plugins and removing any that are no longer referenced:
```shell
npx quartz plugin install --from-config
```
### Testing with Branches
If a plugin author has a fix or feature on a separate branch, you can install it directly without waiting for a release to the default branch:
```shell
# Install from a feature branch
npx quartz plugin add github:username/repo#fix/some-bug
# Later, switch back to the default branch by re-adding without a ref
npx quartz plugin remove repo
npx quartz plugin add github:username/repo
```
The branch ref is tracked in `quartz.lock.json`, so `install --latest` will continue to follow the specified branch until the plugin is re-added without one.
Both `prune` and `install --from-config` will fall back to `quartz.config.default.yaml` if no `quartz.config.yaml` is present.
### Local Plugin Development
For local plugin development or airgapped environments, you can add a plugin from a local directory:
```shell
npx quartz plugin add ./my-local-plugin
```
Local plugins are symlinked into `.quartz/plugins/`, so changes reflect immediately. When you run `install --latest`, local plugins are rebuilt (npm install + npm run build) without any git operations.
> [!note]
> Local symlinked plugins typically use this build-on-install fallback because the `dist/` directory is usually gitignored during development.
The `install --latest --dry-run` command will show local plugins with a "local" status instead of checking for remote updates.
To switch a local plugin back to a git source:
```shell
npx quartz plugin remove my-local-plugin
npx quartz plugin add github:username/my-local-plugin
```
### Subdirectory (Monorepo) Plugins
Some plugins live in a subdirectory of a larger repository rather than at the root. For these, you can specify the plugin source as an object in `quartz.config.yaml` with a `subdir` field:
```yaml title="quartz.config.yaml"
plugins:
- source:
repo: "https://github.com/username/monorepo.git"
subdir: plugin
enabled: true
```
This tells Quartz to clone the full repository but install only the contents of the specified subdirectory.
You can combine `subdir` with `ref` to pin a branch or tag, and `name` to override the plugin directory name:
```yaml title="quartz.config.yaml"
plugins:
- source:
repo: "https://github.com/username/monorepo.git"
subdir: packages/my-plugin
ref: v2.0
name: my-plugin
enabled: true
```
See [[configuration#Advanced Source Options|Advanced Source Options]] for the full reference on object source fields.
> [!note]
> The `plugin add` CLI command works with string sources. To use the object source format with `subdir`, edit `quartz.config.yaml` directly, then run `npx quartz plugin install --from-config` to install it.
## Migration from Deprecated Commands
| Old command | New equivalent |
| ------------------------------------- | --------------------------------------------------- |
| `npx quartz plugin restore` | `npx quartz plugin install --clean` |
| `npx quartz plugin update` | `npx quartz plugin install --latest` |
| `npx quartz plugin update my-plugin` | `npx quartz plugin install --latest my-plugin` |
| `npx quartz plugin check` | `npx quartz plugin install --latest --dry-run` |
| `npx quartz plugin resolve` | `npx quartz plugin install --from-config` |
| `npx quartz plugin resolve --dry-run` | `npx quartz plugin install --from-config --dry-run` |
| `npx quartz update` | `npx quartz plugin install --latest` |
The old commands still work as hidden aliases but will print a deprecation warning.
## Plugin Status
Running the plugin command without any subcommand shows a status dashboard of all installed plugins, including whether updates are available:
```shell
npx quartz plugin
```
This displays each plugin with its source, commit, enabled/disabled status, and checks for available updates in parallel. For the full interactive management interface, use [[tui|npx quartz tui]] instead.
Local/storage/thlab-notes/worker/docs/cli/restore.md
+31
View File
@@ -0,0 +1,31 @@
---
title: quartz restore
---
The `restore` command is a safety mechanism that allows you to recover your **content folder** from a local cache. This command only affects your Markdown files and does not restore plugins or configuration.
To restore plugins to a specific state, use [[cli/plugin|npx quartz plugin install]].
## When to Use
You should use `restore` if:
- A `quartz upgrade` failed and corrupted your content.
- You accidentally deleted files in your content folder.
- You encountered complex merge conflicts that you want to undo.
## How it Works
Quartz maintains a hidden cache of your content folder. Every time you run certain commands, Quartz ensures that a backup of your Markdown files exists. The `restore` command simply copies these files back into your main content directory.
```shell
npx quartz restore
```
## Example Workflow
If an update fails and leaves your project in a broken state:
1. **Restore**: Run `npx quartz restore` to bring back your content.
2. **Clean**: Use Git to reset any other broken code files.
3. **Retry**: Attempt the update again or manually apply the changes you need.
Local/storage/thlab-notes/worker/docs/cli/sync.md
+74
View File
@@ -0,0 +1,74 @@
---
title: quartz sync
---
The `sync` command automates the process of pushing your local changes to GitHub and pulling updates from your remote repository. It simplifies the Git workflow for users who want to keep their site updated without running manual Git commands.
## Flags
| Flag | Shorthand | Description | Default |
| ------------- | --------- | ------------------------------------ | ----------------- |
| `--directory` | `-d` | The directory of your Quartz project | Current directory |
| `--verbose` | `-v` | Enable detailed logging | `false` |
| `--commit` | | Whether to commit changes | `true` |
| `--no-commit` | | Skip committing changes | `false` |
| `--message` | `-m` | Custom commit message | `update content` |
| `--push` | | Whether to push changes to remote | `true` |
| `--no-push` | | Skip pushing changes | `false` |
| `--pull` | | Whether to pull changes from remote | `true` |
| `--no-pull` | | Skip pulling changes | `false` |
## Workflow
When you run `npx quartz sync`, Quartz performs the following steps:
1. **Pull**: It fetches and merges changes from your remote GitHub repository.
2. **Add**: It stages all new and modified files in your project.
3. **Commit**: It creates a new commit with your changes.
4. **Push**: It sends your new commit to GitHub.
## Common Workflows
### Regular Sync
The most common usage is to simply run the command with no flags. This pulls, commits, and pushes everything.
```shell
npx quartz sync
```
### First Sync
If you have just set up a new repository and haven't pushed anything yet, you might want to skip the pull step.
```shell
npx quartz sync --no-pull
```
### Custom Commit Message
You can provide a more descriptive message for your changes.
```shell
npx quartz sync --message "add new notes about gardening"
```
### Sync from Another Device
If you are working on a different computer and just want to get the latest changes without pushing anything back yet.
```shell
npx quartz sync --no-push --no-commit
```
## Troubleshooting
### Git Buffer
If you have a very large number of changes, Git might occasionally fail due to buffer limits. If this happens, try syncing smaller batches of files or increasing your Git post buffer size.
### Autostash
Quartz uses `git pull --rebase --autostash` internally. This means if you have unstaged changes when you run `sync`, Quartz will temporarily hide them, pull the remote changes, and then bring your changes back. If a conflict occurs during this process, you will need to resolve it manually using standard Git tools.
For more information on initial setup, see [[installation]].
Local/storage/thlab-notes/worker/docs/cli/tui.md
+64
View File
@@ -0,0 +1,64 @@
---
title: quartz tui
---
The `tui` command launches an interactive terminal user interface for managing your Quartz project. It provides a visual way to manage plugins, arrange your site layout, and edit general settings.
## Prerequisites
To use the TUI, you must have the following:
1. **Bun**: The TUI requires the Bun runtime. You can find installation instructions at [bun.sh](https://bun.sh/docs/installation).
2. **TUI Plugin**: You must install the TUI plugin in your Quartz project.
### Installation
Run the following command to add the TUI plugin:
```shell
npx quartz plugin add github:quartz-community/tui
```
## Interface Panels
The TUI is divided into three main panels that you can navigate between.
### Plugins Panel
This panel allows you to browse all available and installed plugins. You can:
- Enable or disable plugins with a single keystroke.
- Configure plugin-specific settings.
- Install new plugins from the community or remove existing ones.
### Layout Panel
The Layout panel is where you define where components appear on your site. You can:
- Move components between different sections (e.g. `left`, `right`, `beforeBody`).
- Reorder components within a section to change their vertical stack.
- Set priorities for components to control their placement.
### Settings Panel
This panel provides a central place to edit your `quartz.config.yaml` settings. You can update:
- `pageTitle`
- Theme colors and fonts
- Analytics configuration
- Deployment settings
## Navigation
The TUI uses standard terminal navigation keys:
- **Arrow Keys**: Move between items and panels.
- **Enter**: Select an item or confirm a change.
- **Esc**: Go back or cancel an action.
- **Tab**: Cycle through different interface elements.
## Important Note
All changes made within the TUI are written directly to your `quartz.config.yaml` file. It is a good practice to have a clean Git state before using the TUI so you can easily review and undo any changes it makes.
For command-line based plugin management, see [[cli/plugin|quartz plugin]].
Local/storage/thlab-notes/worker/docs/cli/upgrade.md
+48
View File
@@ -0,0 +1,48 @@
---
title: quartz upgrade
---
The `upgrade` command upgrades the Quartz framework itself to the latest version by pulling changes from the official Quartz repository.
## Usage
```shell
npx quartz upgrade
```
## How it Works
When you run `npx quartz upgrade`, Quartz performs the following steps:
1. **Backs up your content** — your content folder is cached locally to prevent data loss.
2. **Pulls the latest Quartz code** — fetches and merges from the official upstream repository (`upstream/v5`) using Git.
3. **Shows version changes** — displays the version transition (e.g., `v5.0.0 → v5.1.0`) or confirms you're already up to date.
4. **Updates dependencies** — runs `npm install` to ensure all packages match the new version.
5. **Restores plugins** — reinstalls plugins from `quartz.lock.json` to ensure compatibility.
6. **Checks plugin compatibility** — verifies that installed plugins are compatible with the new Quartz version.
## Handling Conflicts
Because Quartz allows you to customize almost every part of the code, upgrades can sometimes result in merge conflicts. This happens if you have modified a file that the Quartz team has also updated.
Quartz automatically handles merge conflicts in `quartz.lock.json` by backing up your lockfile before pulling and restoring it afterward. This prevents the most common source of conflicts during upgrades.
For other files, if a conflict occurs:
1. Git will mark the conflicting sections in the affected files.
2. You will need to open these files and manually choose which changes to keep.
3. After resolving the conflicts, you can commit the changes.
## Recovery
If an upgrade goes wrong or leaves your project in an unusable state, you can use the [[restore|restore]] command to recover your content from the local cache.
## Flags
The `upgrade` command supports the standard [[cli/index|common flags]] (`--directory`, `--verbose`).
## See Also
- [[cli/plugin|quartz plugin install --latest]] — update installed plugins
- [[upgrading|Upgrading Quartz]] — detailed upgrading guide
- [[restore|quartz restore]] — recover content from cache