Skip to main content
The sync command manages bidirectional synchronization between your local Quartz content and GitHub, handling commits, pulls, and pushes automatically.

​
Basic Usage

npx quartz sync [options]
By default, this command:
  1. Commits your local changes with a timestamp
  2. Pulls updates from your GitHub repository
  3. Pushes your changes to GitHub

​
Command Options

​
Commit Options

​
--commit
boolean
default:"true"
Create a git commit for your unsaved changes.
npx quartz sync --commit
When enabled, the sync command stages all changes and creates a commit with a timestamp before pulling or pushing.
To skip committing:
npx quartz sync --no-commit
​
--message
string
Custom commit message (overrides the default timestamp message).Alias: -m
npx quartz sync --message "Updated blog posts"
Default message format: Quartz sync: Jan 15, 2026, 2:30 PM

​
Remote Sync Options

​
--pull
boolean
default:"true"
Pull updates from your Quartz fork before pushing.
npx quartz sync --pull
You may need to resolve git conflicts if remote changes conflict with your local modifications.
To skip pulling:
npx quartz sync --no-pull
​
--push
boolean
default:"true"
Push updates to your Quartz fork.
npx quartz sync --push
The push uses force-with-lease to safely update the remote branch.To skip pushing:
npx quartz sync --no-push

​
Common Options

​
--directory
string
default:"content"
Directory containing your content files.Alias: -d
npx quartz sync --directory ./my-notes
​
--verbose
boolean
default:"false"
Print extra logging information.Alias: -v
npx quartz sync --verbose

​
Examples

​
Full Sync (Default)

Commit, pull, and push all changes: 
npx quartz sync
This performs the complete workflow with automatic commit message.

​
Custom Commit Message

Sync with a descriptive commit message: 
npx quartz sync -m "Add new article"

​
Pull Only

Get updates from GitHub without committing or pushing: 
npx quartz sync --no-commit --no-push

​
Push Only

Push local changes without pulling: 
npx quartz sync --no-pull
Skipping pull may cause push failures if the remote has newer changes.

​
Commit Without Sync

Create a commit without pulling or pushing: 
npx quartz sync --no-pull --no-push

​
Sync Workflow

The sync command executes these steps in order:
1

Content Backup

Backs up your content folder to .quartz-cache/content-cache to ensure no data loss during the sync process.
2

Symlink Handling

If your content folder is a symlink:
  • Detects the symlink
  • Dereferences it to get the actual content
  • Creates a temporary copy for committing
  • Restores the symlink after commit
# Works seamlessly with symlinked content
ln -s ~/Documents/Notes content
npx quartz sync
3

Commit Creation (if --commit)

Stages all changes and creates a commit:
git add .
git commit -m "Quartz sync: <timestamp>"
4

Pull Updates (if --pull)

Pulls changes from the origin remote:
git pull origin <current-branch>
May require conflict resolution if local and remote changes overlap.
5

Push Changes (if --push)

Pushes to the current branch with force-with-lease:
git push -uf origin <current-branch>
6

Content Restoration

Restores your content folder from the cache, preserving symlinks if they existed.
Quartz sync intelligently handles symlinked content folders: 
# Create a symlink to your notes
ln -s ~/Dropbox/Notes content

# Sync works automatically
npx quartz sync
The command will:
  • Detect the symlink
  • Temporarily dereference it for git operations
  • Restore the symlink after committing
  • Preserve timestamps and permissions
This allows you to keep your content in cloud storage (Dropbox, iCloud, etc.) while still using Quartz.

​
Git Configuration

The sync command uses these git remotes:
  • origin: Your personal Quartz repository fork
  • upstream: The official Quartz repository (for updates)
Ensure your origin is configured: 
git remote -v
Expected output: 
origin    https://github.com/yourusername/quartz.git (fetch)
origin    https://github.com/yourusername/quartz.git (push)
upstream  https://github.com/jackyzha0/quartz.git (fetch)
upstream  https://github.com/jackyzha0/quartz.git (push)

​
Common Workflows

​
Daily Content Updates

# Make changes to your content
nano content/blog/my-post.md

# Sync to GitHub
npx quartz sync -m "Update blog post"

​
Sync After Batch Edits

# Edit multiple files
# ...

# Sync all changes at once
npx quartz sync -m "Weekly content update"

​
Collaborative Workflow

# Pull latest changes from team
npx quartz sync --no-commit --no-push

# Make your edits
# ...

# Commit and push your changes
npx quartz sync -m "Add my contributions"

​
Troubleshooting

​
Merge Conflicts

If you encounter merge conflicts during pull:
1

Resolve conflicts manually

# Edit conflicting files
nano content/conflicting-file.md

# Stage resolved files
git add content/conflicting-file.md
2

Complete the merge

git commit -m "Resolve merge conflicts"
3

Push changes

npx quartz sync --no-commit --no-pull

​
Push Rejected

If your push is rejected: 
# Pull first to get remote changes
npx quartz sync --no-commit --no-push

# Then push
npx quartz sync --no-commit --no-pull
If symlink dereferencing fails:
Ensure the symlink target is accessible and contains valid content.
# Check symlink target
ls -l content

# Verify target exists
readlink content

​
Advanced Usage

​
Selective Sync Operations

npx quartz sync --no-pull --no-push
Creates a local commit without interacting with GitHub.
npx quartz sync --no-commit --no-push
Gets latest changes without committing local work.
npx quartz sync --no-pull
Pushes local commits (risky if remote has changes).

​
Integration with CI/CD

# In your deployment script
npx quartz build
npx quartz sync --message "Deploy: $(date)"

​
Safety Features

The sync command includes several safety mechanisms:
  • Content caching: Your content is backed up before any git operations
  • Force-with-lease: Prevents accidental overwrites of remote changes
  • Symlink preservation: Original symlinks are restored after operations
  • Timestamp preservation: File timestamps are maintained during operations

​
Source Code Reference

The sync command implementation:
  • quartz/bootstrap-cli.mjs:32 - Command definition
  • quartz/cli/handlers.js:554 - Sync handler function
  • quartz/cli/args.js:37 - Argument definitions
  • quartz/cli/helpers.js:24 - Content stashing utilities

​
Next Steps

Build Command

Build your site before syncing

Deployment

Deploy your Quartz site to hosting platforms

Build docs developers (and LLMs) love

Get started for freeTalk to us