nb sync, nb remote, and nb git — Sync and Version Control

nb uses Git under the hood to version-control every change to your notebooks. With nb remote, nb sync, and nb git you can push notebooks to any Git hosting service, keep multiple machines in sync automatically, and run raw git commands when you need full control. Each notebook has its own independent git history, so you can sync some notebooks to a remote while keeping others local.

nb sync

nb sync manually syncs the current notebook with its configured remote repository.

Usage

nb sync [-a | --all]

Options

-a, --all

flag

Sync all unarchived notebooks that have a remote configured.

How Automatic Sync Works

Any notebook with a remote URL configured will sync automatically every time a command is run in that notebook (e.g. nb add, nb edit, nb delete). To disable this behavior, set nb set auto_sync 0.

Manual Sync

# sync the current notebook
nb sync

# sync a specific notebook by selector
nb example:sync

# sync all notebooks at once
nb sync --all

Conflict Resolution

When nb sync encounters a text file conflict that cannot be cleanly merged, both versions are saved in the file separated by git conflict markers:

# Example Title

- List Item apple
<<<<<<< HEAD
- List Item apricot
=======
- List Item pluot
>>>>>>> 719od01... [nb] Commit
- List Item plum

Use nb edit to remove the conflict markers and delete the unwanted version. To keep both items, simply delete the three marker lines:

# Example Title

- List Item apple
- List Item apricot
- List Item pluot
- List Item plum

When nb sync encounters a binary file conflict (e.g. an encrypted note), both versions are saved as individual files. The remote version gets --conflicted-copy appended to its filename. Resolve by comparing the two files, merging manually, then deleting the --conflicted-copy.

nb remote

nb remote configures the Git remote URL and branch for the current notebook.

Usage

nb remote
nb remote branches [<url>]
nb remote delete <branch-name>
nb remote remove
nb remote rename [<branch-name>] <name>
nb remote reset <branch-name>
nb remote set <url> [<branch-name>]

Subcommands

Subcommand	Description
(default)	Print the current remote URL and branch
`set`	Set the remote URL and optionally a branch name
`remove`	Remove the remote URL from the notebook. Alias: `unset`
`branches`	List all branches on the current or a given remote
`rename`	Rename the current orphan branch or a named branch
`delete`	Delete an orphan branch from the remote
`reset`	Reset a remote branch to a blank initial state

Setting a Remote

# set the remote for the current notebook
nb remote set https://github.com/example/example.git

# set the remote for a specific notebook
nb example-notebook:remote set https://github.com/example/example.git

# set the remote and specify a branch
nb remote set https://github.com/xwmx/example demo-branch

Removing a Remote

# remove the remote from the current notebook
nb remote remove

# remove the remote from a specific notebook
nb example:remote remove

Listing Remote Branches

# list all branches on the current remote
nb remote branches

# list all branches on a specific remote URL
nb remote branches "https://github.com/xwmx/example"

Syncing Multiple Notebooks to One Remote

You can sync multiple notebooks to a single remote repository using orphan branches — branches with independent git histories that share no common ancestry with the main branch. When you run nb remote set, nb will offer to create a new orphan branch. The branch name is derived from the notebook name, or you can specify it explicitly:

nb remote set https://github.com/xwmx/example demo-branch

To use an existing orphan branch on a remote, pass the branch name when initializing or adding a notebook:

# initialize "home" from an existing orphan branch
nb init https://github.com/xwmx/example sample-branch

# add a new notebook from an orphan branch
nb notebooks add example https://github.com/xwmx/example example-branch

nb git

nb git runs git commands directly within the current notebook directory, bypassing nb logic. Use it for advanced operations that nb doesn’t expose, or when you need to resolve a conflict manually.

Usage

nb git [checkpoint [<message>] | dirty]
nb git <git-options>...

Subcommands

checkpoint [<message>]

subcommand

Create a new git commit in the current notebook and sync with the remote if nb set auto_sync is enabled. Optionally provide a custom commit message.

dirty

subcommand

Exit with status 0 (success / true) if there are uncommitted changes in the current notebook. Exit with status 1 (error / false) if the notebook is clean.

Pass-Through Git Commands

Any git command and its arguments can be passed directly:

# check git status in the current notebook
nb git status

# view the git log
nb git log

# fetch from origin
nb git fetch origin

# view a diff
nb git diff

# run git status in the "example" notebook
nb example:git status

Manual Checkpoint

Create a commit manually, with an optional custom message:

nb git checkpoint
nb git checkpoint "My manual commit message"

nb status

nb status prints the archival, git, and remote status for the current notebook or a named notebook.

Usage

nb status [<notebook>]

Examples

# status for the current notebook
nb status

# status for a specific notebook
nb status example

# shortcut alias
nb st
nb st example

nb init

nb init initializes the initial home notebook and generates the ~/.nbrc configuration file. Pass a remote URL and optional branch to clone an existing notebook instead of starting fresh.

Usage

nb init [<remote-url> [<branch>]] [--author] [--email <email>] [--name <name>]

Options

<remote-url>

string

URL of an existing remote repository to clone as the initial home notebook.

string

Branch name to check out from the remote. Used to access orphan branches storing specific notebooks.

--author

flag

Display the local email and name configuration prompt.

--email <email>

string

Set the local git commit author email address.

--name <name>

string

Set the local git commit author name.

Examples

# initialize nb for the first time
nb init

# initialize by cloning an existing remote notebook
nb init https://github.com/example/example.git

# initialize from a specific branch on the remote
nb init https://github.com/example/example.git example-branch

Setting Up Sync with GitHub or GitLab

Create a private repository

Create a new private repository on GitHub or GitLab. Do not initialize it with a README.

Configure git credentials

For HTTPS, cache credentials so git doesn’t prompt for a password on every sync:

git config --global credential.helper cache

For SSH, generate a key and add it to the ssh-agent:

ssh-keygen -t ed25519 -C "your_email@example.com"
ssh-add ~/.ssh/id_ed25519

Set the remote for your notebook

# HTTPS
nb remote set https://github.com/yourusername/your-repo.git

# SSH
nb remote set git@github.com:yourusername/your-repo.git

Sync manually to verify

nb sync

If a password prompt appears, credentials are not yet cached — follow the git credentials guide for your method.

Sync on a second machine

Clone the existing notebook on another system:

nb notebooks add home https://github.com/yourusername/your-repo.git

From this point, nb syncs automatically on every write operation.

Using Dropbox, Drive, or Syncthing Instead

You can also sync notebooks using any file-syncing service by changing the notebooks directory:

nb set nb_dir ~/Dropbox/Notes

Git sync will still work simultaneously alongside file-syncing.

Examples

# check remote config for the current notebook
nb remote

# set a remote
nb remote set https://github.com/example/example.git

# sync manually
nb sync

# sync all notebooks
nb sync --all

# create a manual git checkpoint
nb git checkpoint "Before major reorganization"

# check if there are uncommitted changes
nb git dirty && echo "notebook has uncommitted changes"

# view git log
nb git log --oneline -10

# check status
nb status

To sync a notebook silently without output, use nb sync — it runs in the background automatically on every notebook-modifying command when auto_sync is enabled (the default). You only need nb sync manually when working offline or when you want to pull in remote changes without making a local change first.

Syncing with private repositories requires git credentials to be configured so that git does not prompt for a password. If nb sync shows a password prompt, no changes will be committed until credentials are properly set up. See the GitHub credentials caching guide for HTTPS, or the SSH key guide for SSH.

Command Reference

Advanced

nb sync, nb remote, and nb git — Sync and Version Control

nb sync

Usage

Options

How Automatic Sync Works

Manual Sync

Conflict Resolution

nb remote

Usage

Subcommands

Setting a Remote

Removing a Remote

Listing Remote Branches

Syncing Multiple Notebooks to One Remote

nb git

Usage

Subcommands

Pass-Through Git Commands

Manual Checkpoint

nb status

Usage

Examples

nb init

Usage

Options

Examples

Setting Up Sync with GitHub or GitLab

Using Dropbox, Drive, or Syncthing Instead

Examples

Build docs developers (and LLMs) love

Command Reference

Advanced

Documentation Index

​nb sync

​Usage

​Options

​How Automatic Sync Works

​Manual Sync

​Conflict Resolution

​nb remote

​Usage

​Subcommands

​Setting a Remote

​Removing a Remote

​Listing Remote Branches

​Syncing Multiple Notebooks to One Remote

​nb git

​Usage

​Subcommands

​Pass-Through Git Commands

​Manual Checkpoint

​nb status

​Usage

​Examples

​nb init

​Usage

​Options

​Examples

​Setting Up Sync with GitHub or GitLab

​Using Dropbox, Drive, or Syncthing Instead

​Examples

Build docs developers (and LLMs) love

nb sync

Usage

Options

How Automatic Sync Works

Manual Sync

Conflict Resolution

nb remote

Usage

Subcommands

Setting a Remote

Removing a Remote

Listing Remote Branches

Syncing Multiple Notebooks to One Remote

nb git

Usage

Subcommands

Pass-Through Git Commands

Manual Checkpoint

nb status

Usage

Examples

nb init

Usage

Options

Examples

Setting Up Sync with GitHub or GitLab

Using Dropbox, Drive, or Syncthing Instead

Examples