Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xwmx/nb/llms.txt

Use this file to discover all available pages before exploring further.

Every time you add, edit, or delete a note, nb silently records that change as a Git commit in the notebook’s local repository. This means every notebook is a full Git repo from the moment it is created — no setup required. When you attach a remote to a notebook, those commits can be pushed and pulled automatically, giving you seamless, version-controlled sync across any number of machines without ever running a Git command yourself.

​
How nb Uses Git

Each notebook directory is an independent Git repository. nb calls git commit in the background after every operation that modifies the notebook’s contents — adds, edits, deletes, and moves are all captured automatically. Because each notebook has its own Git history, you can sync some notebooks to remote repositories while keeping others entirely local.

​
Setting and Viewing a Remote

Use nb remote set to attach a remote URL to the current notebook: 
# set the current notebook's remote to a private GitHub repository
nb remote set https://github.com/example/example

# set the remote for a notebook named "example"
nb example:remote set https://github.com/example/example

# set the remote and specify a branch name
nb remote set https://github.com/xwmx/example demo-branch
View the currently configured remote for the active notebook: 
nb remote
Remove the remote when you no longer want a notebook to sync: 
# remove the remote from the current notebook
nb remote remove

# remove the remote from the notebook named "example"
nb example:remote remove

​
Cloning an Existing Remote Notebook

To pull an existing remote notebook down to a new machine, pass the URL to nb notebooks add: 
# create a new notebook named "example" cloned from a private GitLab repository
nb notebooks add example https://gitlab.com/example/example.git

​
Syncing

Once a remote is set, nb syncs that notebook automatically every time a command runs within it. You can also sync on demand: 
# manually sync the current notebook
nb sync

# manually sync the notebook named "example"
nb example:sync

# sync all notebooks that have a remote configured
nb sync --all

​
Auto-Sync Configuration

Auto-sync is enabled by default. The auto_sync setting controls whether nb pushes and pulls on every git checkpoint call: 
# disable auto-sync
nb set auto_sync 0

# re-enable auto-sync
nb set auto_sync 1
The $NB_AUTO_SYNC and $NB_AUTO_SYNC_SECONDS environment variables provide additional control:
VariableDefaultDescription
$NB_AUTO_SYNC1Set to 0 to disable automatic syncing entirely.
$NB_AUTO_SYNC_SECONDS60Minimum seconds between automatic sync operations. Set to 0 to sync on every commit.

​
Syncing Multiple Notebooks to One Remote

Multiple notebooks can share a single remote repository by using orphan branches — branches whose history is completely independent from the repository’s primary branch. When you run nb remote set, nb gives you the option to create a new orphan branch. You can also specify a branch name directly: 
# sync the current notebook to a specific branch on the remote
nb remote set https://github.com/xwmx/example demo-branch
To start a new notebook from an existing orphan branch on a remote: 
# initialize "home" notebook from the branch "sample-branch"
nb init https://github.com/xwmx/example sample-branch

# add a new "example" notebook from the branch "example-branch"
nb notebooks add example https://github.com/xwmx/example example-branch
List all branches available on a remote: 
# list all branches on the current notebook's remote
nb remote branches

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

​
Private Repositories and Git Credentials

Syncing with private repositories requires configuring Git so it does not prompt for credentials during an automated sync.
Use nb sync within the notebook to test your credential setup. If a password prompt appears, credentials are not yet configured correctly. nb does not cache or store Git credentials itself.

​
Sync Conflict Resolution

nb handles Git operations automatically and resolves most conflicts without any manual intervention using a union merge strategy. Text file conflicts: When nb sync finds overlapping local and remote changes that cannot be cleanly merged, it saves both versions inside the file separated by standard Git conflict markers and prints a message identifying the affected files. Use nb edit to open the file, remove the conflict markers, and keep the content you want: 
# Example Title

- List Item apple
<<<<<<< HEAD
- List Item apricot
=======
- List Item pluot
>>>>>>> 719od01... [nb] Commit
- List Item plum
Remove the <<<<<<<, =======, and >>>>>>> lines to resolve: 
# Example Title

- List Item apple
- List Item apricot
- List Item pluot
- List Item plum
Binary file conflicts: For binary files (such as encrypted notes), nb saves both versions as separate files in the notebook, appending --conflicted-copy to the filename of the remote version. Compare them, merge manually, and delete the --conflicted-copy file to resolve.

​
Running Raw Git Commands

To run arbitrary Git commands directly inside a notebook’s directory, use nb git: 
# run git fetch in the current notebook
nb git fetch origin

# check the git status of the notebook named "example"
nb example:git status

# view the full git diff
nb git diff

​
Checkpoints

nb git checkpoint creates a manual commit and syncs with the remote (if auto-sync is enabled): 
# create a checkpoint with a custom commit message
nb git checkpoint "WIP: drafting quarterly report"

# create a checkpoint with no message
nb git checkpoint

​
Dirty State

nb git dirty exits with 0 (success) if there are uncommitted changes in the notebook, or 1 if the notebook is clean — useful in scripts: 
if nb git dirty; then
  echo "Notebook has uncommitted changes"
fi

​
Notebook Status

nb status prints a summary of the current notebook, including remote URL, branch, and any pending changes: 
# show status for the current notebook
nb status

# show status for the notebook named "example"
nb status example

​
Alternative Sync with Dropbox or rsync

If you prefer to sync notes through a cloud storage service instead of (or in addition to) Git remotes, point nb’s notebook directory at a Dropbox, Google Drive, Box, or Syncthing folder: 
# move all notebooks into a Dropbox folder
nb settings set nb_dir ~/Dropbox/Notes
Git versioning continues to work within that directory, so you get both local Git history and cloud sync simultaneously.

Build docs developers (and LLMs) love

Get started for freeTalk to us