ThoughtSync

README

Edit notes at the speed of thought

📝 What is this?

ThoughtSync is a CLI tool that allows users to access their own note collection, comfortably from the command line, using their own EDITOR.

It offers git support to add and commit changes to users note, with an option to support git remotes and pulling/pushing changes.

ThoughtSync was born to be used with an Obsidian-type vault in mind, but it is compatible with just any note collection contained in a single folder. This collection is commonly referred to as a vault.

💻 Tech Stack

ThoughtSync is built in go using the cobra framework and a handful of other go libraries like go-editor and go-git. Some other tools used are:

• mise-en-place, a polyglot runtime manager to handle tool versions, env vars and much more
• mockery, mock generator for go interfaces
• testify, a go toolkit to write tests
• color to print colored text to the terminal
• gotestsum, a wrapper for the go test command
• act for testing github actions locally
• color to print colored text to the terminal

✨ Features

ThoughtSync lets the user open, edit and search through their own note collection. Current features include:

• Editing an existing note;
• Create a new note in any subdirectory in their own vault;
• Create or open the note entry for the current day, useful when keeping a daily journal
• Configure note vault path, journal directory, note format and much more
• Keep track of your vault changes using git and optionally sync it with a remote repository

⚙️ Roadmap

• Ability to search through notes using popular tools such as ripgrep
• Quickly group notes with a certain tag or containing a certain word
• Quickly read a note content without opening it using cat or similar
  • Freely select the program used (i.e. cat, bat, etc) to output the file contents
• Preferences in a single configuration file
• Quickly get and set configuration options
• Git syncing with remote options
• Fuzzy find notes in your vault and open them
• See the vault git status
• Open a tree view of your vault for easy navigation

🚀 Installation

ThoughtSync can be installed as any go product with go install:

go install github.com/lcampit/ThoughtSync

or simply by downloading the executable from the releases page

It's suggested to use an alias such as alias ts=ThoughtSync

🔥 Usage

The following is a list of available commands:

• thoughtsync new <filename.txt> to create a new note in your vault
• thoughtsync today to create and/or open the journal note of today
• thoughtsync inbox to quickly open an inbox note to store thoughts and ideas, to be processed later
• thoughtsync vault to open the vault directory in your editor
• thoughtsync edit to fuzzy find and open the selected note in your editor
• thoughtysync git contains all git-related commands:
  • sync to stage, commit and optionally push your vault to your remote git repository.
  • status to see the current vault git status
  • push manually pushes changes to the remote vault git repository
  • pull manually pulls changes from the remote vault git repository
• thoughtsync config contains all options related to the tool configuration:
  • The base commands prints the current configuration options in a nicely indented view
  • set sets a configuration options using the given value and saves the configuration changes
• thoughtsync read to fuzzy find among all notes and output a note's contents on the terminal

⚙️ Configuration

ThoughtSync can be configured using a thoughtsync.yaml file contained in $XDG_CONFIG_HOME/thoughtsync/thoughtsync.yaml

The configuration file is defined as follows:

• The vault section contains all configuration related to the note vault
  • path contains the full path to the vault main directory
  • extension contains the extension of the notes files in your vault
• The journal section contains all configuration related to the journal notes:
  • directory contains the path, relative to vault.path, to store your journal notes in
  • format defines the format used to give a name to your journal notes, such as "2006-02-01", without extension
    • currently supported formats are YYYY-MM-DD, MM-DD-YYYY
• The git section contains all options related to managing your notes with git:
  • enable enables git support
  • remote enables git remote support and pushing to the remote with thoughtsync sync (has no effect if git.enable is false)
  • remote-name sets the git remote name to push to / pull from
  • commit-message contains the commit message used with thoughtsync git sync
  • ssh to use ssh authentication for your vault git-related commands

Here's an exhaustive configuration example:

# Contains all vault specific options
vault:
  path: $HOME/vault # Default: $HOME/thoughtsync
  extension: ".txt" # Default: ".md"

# Contains all journal specific options
journal:
  directory: my-own-journal # Default: journal
  format: "YYYY-MM-DD" # Default: "YYYY-MM-DD"

# Contains all git specific options
git:
  enable: true # default false
  remote: true # default false
  remote-name: "remote" # default origin
  commit-message: "thoughtsync sync" # default "thoughtsync: Synced with git"
  ssh: true # default false

[!NOTE] Some configuration options need to be the expected type, i.e. booleans for the enable/disable options. If the options provided from the configuration file are not valid, the default one will be silently used

🏃♂ Running the project

The CLI itself has a proper help message accessible with the --help or -h flags. If you clone the repo, there are some pre-built tasks defined to make the development experience easier.
Assuming mise is installed:

• mise run build will build the project in a single executable ThoughtSync
• mise run test will run tests

🔆 Contributing

Contributions are welcome! Feel free to clone the project and create pull requests or add issues.

📅 How did it start?

I've been caressing the idea of building my own second brain with notes since I had a job. Being able to write down stuff helps me keep a clear head, so I started building my own second brain using Notion. I've always wanted to be fluent with the command line, but I could not find proper ways to access my notes in Notion through the CLI, at least until I found out this video that showed me how to combine Neovim with Note taking in Obsidian. I made the switch, but I noticed how the video author used bash scripts to access its own vault. Surely there is some CLI tool I can use for that, right? No? Time to create my own then!

Documentation

Overview

Copyright © 2024 Leonardo Campitelli leonardo932.campitelli@gmail.com