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 add, edit, and delete in nb is silently committed to the notebook’s local Git repository. This means that the complete revision history of every note is always available — no manual saves, no separate backup step, and no third-party service required. You can browse the history of a single note or an entire notebook, inspect exactly when changes were made, and see which author made them.

​
How nb Records History

Whenever a note is added, modified, or deleted, nb automatically runs a git commit in the background with a generated message describing the operation. The commit records the exact content of the file at that moment, producing a permanent, auditable timeline for every item in the notebook.

​
Viewing History

Use nb history to open the git log for a specific note or for the entire notebook. By default nb history uses git log; when tig is installed it is used automatically for an interactive, ncurses-based log viewer. 
# show history for the current notebook
nb history

# show history for note number 4
nb history 4

# show history for a note by filename
nb history example.md

# show history for a note by title
nb history Example

# show history for the notebook named "example"
nb example:history

# alternative syntax for notebook history
nb history example:

# show history for note 12 in the notebook named "example"
nb history example:12

​
Timestamps: Added and Updated

nb derives timestamps from the Git log rather than the filesystem’s modification time. Use nb show with the --added and --updated flags to query these timestamps directly: 
# print the date and time when note 2 was first committed (added)
❯ nb show 2 --added
2020-01-01 01:01:00 -0700

# print the date and time of the last commit modifying note 2 (updated)
❯ nb show 2 --updated
2020-02-02 02:02:00 -0700
  • --added / -a — displays the datetime of the first Git commit that contains the file.
  • --updated / -u — displays the datetime of the most recent Git commit in which the file was modified.
These timestamps reflect Git commit times, not the filesystem’s mtime. They accurately represent when nb recorded a change, regardless of any filesystem operations that may have occurred outside of nb.

​
Authorship

By default, commits are attributed to the email and name configured in your global Git configuration. You can list the authors of any note with nb show --authors: 
nb show 4 --authors

​
Changing Author Information for a Notebook

Override the commit author for a specific notebook using nb notebooks author: 
# interactively update the commit author for the current notebook
❯ nb notebooks author
Current configuration for: home
--------------------------
email (global): example@example.test
name  (global): Example Name

Update?  [y/N]

# update the commit author for the notebook named "example"
❯ nb notebooks author example
Current configuration for: example
--------------------------
email (global): example@example.test
name  (global): Example Name

Update?  [y/N]
The updated email and name apply to all subsequent commits in that notebook. You can also pass --email and --name directly: 
nb notebooks author --email "you@example.com" --name "Your Name"

​
Setting Author at Notebook Creation

To use a custom author from the very first commit, pass --author (or --email / --name) when creating the notebook: 
# create a new notebook with a custom author identity
nb notebooks add --author

# initialize the current directory as a notebook with a custom author
nb notebooks init --author

# or supply values directly
nb init --email "work@example.com" --name "Work Account"

​
Manual Checkpoints

While nb commits automatically, you can create a named checkpoint at any time using nb git checkpoint. This is useful for marking a meaningful milestone before a major rewrite: 
# create a checkpoint with a descriptive message
nb git checkpoint "Finished first draft of quarterly report"

# create a checkpoint with no message
nb git checkpoint
nb git checkpoint also triggers a sync with the remote if auto_sync is enabled.

​
Running Git Commands Directly

For any operation not covered by nb’s own commands, run Git directly inside the notebook with nb git: 
# view the full git log
nb git log

# show the diff of the last commit
nb git diff HEAD~1

# run git show for a specific commit
nb git show abc1234

​
Checking for Uncommitted Changes

nb git dirty exits with status 0 if the notebook has uncommitted changes, and 1 if it is clean — making it easy to use in shell scripts: 
if nb git dirty; then
  echo "There are uncommitted changes in this notebook"
fi

Build docs developers (and LLMs) love

Get started for freeTalk to us