Logbook

The Logbook project provides a command-line application for Markdown-based chronological note-taking.

Setup

If a computer has the go command and Git installed, the Logbook can be installed by cloning its Git repository and then running the go install command.

git clone git@github.com:experimental-software/logbook.git && cd ./logbook
go install

Then the program can be executed with the logbook2 command:

logbook2

In the ~/.config/logbook/config.yaml file it can be configured what directories are used for reading and writing log entries.

The following snippet shows the configuration options with their default values:

# The directory where new logbook entries are added.
logDirectory: ~/Logs

# The directory where logbook entries are moved when they are archived.
archiveDirectory: ~/Archive

Usage

Add logbook entry

# Add logbook entry
logbook2 add "${TITLE}"

# Add logbook entry and open its root directory in a text editor
${EDITOR} $(logbook2 add "${TITLE}")

Search logbook entries

logbook2 search "${SEARCH_TERM}"

Archive logbook entries

# Archive single logbook entry
logbook2 archive "${PATH}"

# Archive multiple logbook entries
logbook2 archive $(logbook2 search --output-format list "${SEARCH_TERM}")

Remove logbook entries

# Remove single logbook entry
logbook2 remove "${PATH}"

# Remove multiple logbook entries
logbook2 remove $(logbook2 search --output-format list "${SEARCH_TERM}")

Customization

User-specific utilities may be defined with shell features, e.g. this Bash alias and functions on a macOS computer that has VS Code installed:

alias log=logbook2

# Creates logbook entry with title "Scratch Note" and opens it in VS Code.
function note() {
  local LOGBOOK_ENTRY_TITLE="$@"
  if [[ -z "$LOGBOOK_ENTRY_TITLE" ]]; then
    LOGBOOK_ENTRY_TITLE="Scratch Note"
  fi
  LOGBOOK_ENTRY=$(log add "$LOGBOOK_ENTRY_TITLE")
  code "$LOGBOOK_ENTRY"
  code "$LOGBOOK_ENTRY"/*.md
}

# Create logbook entry with architecture decision record
function adr() {
  local SCOPE="$@"
  local LOGBOOK_ENTRY_DIR=$(log add "ADR: $SCOPE")
  cp ~/Vorlagen/adr.md $LOGBOOK_ENTRY_DIR/
  perl -pi -e "s/SCOPE/${SCOPE}/g" $LOGBOOK_ENTRY_DIR/adr.md
  local TODAY=$(date '+%Y-%m-%d')
  perl -pi -e "s/DATE/${TODAY}/g" $LOGBOOK_ENTRY_DIR/adr.md
  code $LOGBOOK_ENTRY_DIR
}

– ~/.bash_profile

Testing

Component test

go test ./... -coverprofile=./cov.out

With the help of the gremlins program, the tests can be executed with mutations:

gremlins unleash

Component integration test

go run main.go
go run main.go search
go run main.go add "Just a test"
go run main.go archive /path/to/2026/01/11/17.28_wip
go run main.go search -a 

Maintenance

Static code analysis

https://sonarcloud.io/summary/overall?id=experimental-software_logbook&branch=main

Alternative projects

• Paper-based engineering logbook
• QOwnNote
• Emacs OrgMode
• Evernote
• Roam Research
• Quiver
• Notion
• Obsidian
• Joplin
• Zettelkasten
• Dendron