stup

A CLI tool to easily save, access and organize daily notes.

The name derives from the Standup meetings since its initial purpose was to cover my need for keeping my Standup notes in a convenient way.

stup Gif demo

How it works

Notes are organized in categories.

When a new note is added, stup creates a markdown file and places it under the category's directory in a sub-directory with a path based on the date.

CATEGORIES_ROOT_DIRECTORY/CATEGORY/YEAR/MONTH/YYYY-MM-DD.md

# For example, the notes of a category named "programming" April 18th, 2020 are saved under
CATEGORIES_ROOT_DIRECTORY/programming/2020/04/2020-04-18.md

This allows users to retrieve any notes added on a specific date or in a specific period for a specific or for all categories.

# Fetch notes for all categories
$ stup show @ 2020-04-18

# Fetch notes for a specific category for previous week
$ stup log previous-week -c programming

# Fetch notes for all categories for a specific period
$ stup log --from 2020-04-01 --to 2020-04-15

Installation

For the moment, the installation is manual until this issue is resolved.

So you have to clone the repository and place the executable stup script in a directory included in your $PATH variable.

git clone https://github.com/iridakos/stup

cd stup

# Given that `~/.local/bin` is included in your $PATH variable
cp ./stup ~/.local/bin

Compatibility

The script has been tested in:

Ubuntu 18.04
Ubuntu 19.10
Debian 9

but it should be running without problems in other Linux Distros as well.

If you face any problems though, feel free to open an issue reporting your Distro and its version.

Configuration

Before you start using stup you have to configure it with:

stup --configure

Follow the wizard to define:

to which directory stup will be saving your notes
what is the name of the default category *
what is the editor you want to use to manually edit your notes when using the edit command
what is the pager you want to use for long outputs (log and usage)

It also asks you if you want to edit the file and change the defaults in case you omit some arguments.

* You can use stup with just a default category but in case you want to add your notes structured for example per project or per any type of section you want, you have the option to create and use multiple categories (see below).

Usage

Add notes

To add a new note use the add command.

$ stup add @ yesterday -n "A note" -n "Another note"

The full version of the command:

stup add @|--at|-@ <when> -n|--note "<note text>" -c|--category "<category-name>"

where:

<when>: specifies in which date the notes should be added. Its value can be:
- any of the words: today, tomorrow, yesterday in which case you can omit the @|--at|-@ option
- a date string in the form: YYYY-MM-DD, for example: 2020-04-12
- if you omit this option, stup by default will save the notes in the current date
<note-text>: the text of the note, for example: "Reviewed PR related to..."
-c or --category: is the category option (optional). If omitted, notes will be saved to your default category
- <category-name>: the name of the category in which the notes will be added

Examples

Add a note for current date (all of the following commands are equivalent)

# Implying today (if you don't define the date, the add action defaults to current date)
$ stup add -n "A new note"

# Explicit with date alias 'today' omitting the `@` option
$ stup add today -n "A new note"

# Explicit with date alias 'today'
$ stup add @ today -n "A new note"

# Explicit without the 'today' alias (suppose the date is April 17th, 2020)
$ stup add @ 2020-04-17 -n "A new note"

Add a note for yesterday

All of the following commands are equivalent.

# Explicit with date alias 'yesterday'
$ stup add @ yesterday -n "A new note"

# Explicit with date alias ommiting the `@` option
$ stup add yesterday -n "A new note"

# Explicit without alias (suppose the date is April 17th, 2020)
$ stup add @ 2020-04-16 -n "A new note"

Add a note for tomorrow

All of the following commands are equivalent.

# Explicit with date alias 'tomorrow'
$ stup add @ tomorrow -n "A new note"

# Explicit with date alias omitting the `@` option
$ stup add tomorrow -n "A new note"

# Explicit without alias (suppose the date is April 17th, 2020)
$ stup add @ 2020-04-18 -n "A new note"

Add two notes at once

$ stup add today -n "Reviewed PR ..." -n "Merged to master..."

Add to a non-default category

# Add a note to a category named 'blocking'
$ stup add -c "blocking" -n "Can't continue unless"

Show notes

To view your notes on a given date, use the show command.

$ stup show

The full version of the command is:

$ stup show @ <when> -c|--category "<category-name>"

where:

@ or --at or -@: is the date option
- <when>: specifies which date's notes should be shown. Its value can be:
  - any of the words: today, tomorrow, yesterday in which case you can omit the @ option
  - a date string in the form: YYYY-MM-DD, example: 2020-04-12
- if you omit this option, stup by default will show you your yesterday's notes
<category-name>: the name of the category whose notes will be shown. You may omit this option if you want to see notes from all the categories.

If you don't specify a category and you have more than one, the default behaviour is to show notes only from the categories that have notes the specified day. If you prefer though to show the "empty" categories as well, you may use the --include-empty.

Notes:

the default action of stup is to show you your notes so you may write the command without the show directive (see the examples).
if you request to view your notes on a date that you haven't added anything, stup will ask if you want to see the notes of the latest date on which something was added before the one you specified.

For example, if it is Monday and you didn't add any notes during the weekend, when you type stup yesterday you'll be prompted to see the notes added on Friday.

Examples

Show yesterday's notes

All of the following commands are equivalent.

# Imply "show" as action and "yesterday" alias as date
$ stup

# Imply "yesterday" as date
$ stup show

# Explicit date set to "yesterday" date alias
$ stup yesterday

# Explicit date (given that current date is April 17th, 2020)
$ stup @ 2020-04-16

Show today's notes

All of the following commands are equivalent.

# Imply "show" as action
$ stup today

# Show today's notes for the category "meetings"
$ stup today -c "meetings"

# Show today's notes for the category "meetings" by explicitly setting action to "show"
$ stup show today -c "meetings"

Show notes on a past date

# Show notes on April's Fool Day
$ stup show @ 2020-04-01

Show notes of a specific category

# Show today's notes added in category "pull-requests"
$ stup show today -n "pull-requests"

Log notes

To list your notes for a given period, use the log command.

$ stup log previous-week

The full version of the command:

$ stup log [--from <from-date>] [--to <to-date>] [--days <days-before/after>] [-c <category-name>]

# or using an alias

$ stup log <week|previous-week|month|previous-month|year|previous-year>

where:

<from-date>: is a date alias (today, yesterday, tomorrow) or a specific date using the format YYYY-MM-DD, for example: 2020-04-18
- this is optional and if omitted the notes to be displayed won't have be added after a specific date
<to-date>: is also a date alias (today, yesterday, tomorrow) or a specific date using the format YYYY-MM-DD, for example: 2020-04-18
- this is also optional and if omitted the notes to be displayed won't have be added before a specific date
-c or --category: is the category option (optional). If omitted, you will view the notes of all categories
- <category-name>: the name of the category whose notes you want to see
days-before/after: When used with --from or --to, denotes how many days after or before that date should be logged; when used alone, that many last days with notes are shown.

In the second version of the command, you can use the temporal aliases that will be translated to proper from/to dates.

In both cases, you may skip the log literal given that you set either an alias or one of the from and to flags.

Examples

Log of this week's notes

$ stup log week

# or

$ stup week

Log of previous week's notes

$ stup log previous-week

# or

$ stup previous-week

Log notes of the last X days, where notes exist

# Log notes of the last 3 days
$ stup log --days 3

# Log notes for the category "meetings", of the last 2 days
$ stup log -c "meetings" --days 2

Log of notes added in a specific period

$ stup log --from 2020-01-15 --to 2020-02-01

# or

$ stup --from 2020-01-15 --to 2020-02-01

Log of notes added in a specific period in the category "blocking"

$ stup log --from 2020-01-15 --to 2020-02-01 -c blocking

# or

$ stup --from 2020-01-15 --to 2020-02-01 -c blocking

Log of notes added after a specific date in the category "blocking"

$ stup log --from 2020-01-15 -c blocking

# or

$ stup --from 2020-01-15 -c blocking

Log of notes added after a specific date and for a specified number of days

$ stup log --from 2020-01-15 --days 4

# or

$ stup --from 2020-01-15 --days 4

Log of notes added up until a specific date going back a specified number of days

$ stup log --to 2020-02-01 --days 4

# or

$ stup --to 2020-02-01 --days 4

Search notes

To search your notes, use the search command.

$ stup search 'jira' previous-week

The full version of the command:

$ stup search <search-text> --from <from-date> --to <to-date> -c <category-name>

# or using an alias

$ stup search <search-text> <week|previous-week|month|previous-month|year|previous-year> -c <category-name>

where:

<search-text>: the text you want to find in notes
<from-date>: is a date alias (today, yesterday, tomorrow) or a specific date using the format YYYY-MM-DD, for example: 2020-04-18
- this is optional and if omitted the notes to be searched won't have to be added after a specific date
<to-date>: is also a date alias (today, yesterday, tomorrow) or a specific date using the format YYYY-MM-DD, for example: 2020-04-18
- this is also optional and if omitted the notes to be searched won't have to be added before a specific date
-c or --category: is the category option (optional). If omitted, you will search the notes of all categories
- <category-name>: the name of the category whose notes you want to see

In the second version of the command, you can use the temporal aliases that will be translated to proper from/to dates.

Examples

Search this week's notes

$ stup search "jira" week

# or

$ stup week search "jira"

Search in previous week's notes

$ stup search "reviewed" previous-week

# or

$ stup previous-week search "linux"

Search notes added in a specific period

$ stup search "cli" --from 2020-01-15 --to 2020-02-01

# or

$ stup --from 2020-01-15 --to 2020-02-01 search "cli"

Search notes added in a specific period in the category "blocking"

$ stup search "SSD" --from 2020-01-15 --to 2020-02-01 -c blocking

# or

$ stup --from 2020-01-15 --to 2020-02-01 -c blocking search "SSD"

Search notes added after a specific date in the category "blocking"

$ stup --from 2020-01-15 -c blocking search "SSD"

# or

$ stup --from 2020-01-15 -c blocking search "SSD"

Edit notes

To manually edit notes added in a specific date use the edit command.

$ stup edit yesterday

The full version of the command as below:

stup edit @|--at|-@ <when> -c|--category "<category-name>"

where:

<when>: specifies in which date the notes should be added. Its value can be:
- any of the words: today, tomorrow, yesterday in which case you can omit the @|--at|-@ option
- a date string in the form: YYYY-MM-DD, for example: 2020-04-12
- if you omit this option, stup by default will edit the notes in the current date
-c or --category: is the category option (optional). If omitted, you will edit the notes of your default category
- <category-name>: the name of the category in which the notes will be added

Note: If there are no notes for a specific date and category, you will be asked if you want to create and edit the file anyway.

Examples

Editing yesterday's notes

# Omitting category option, implying the default one
$ stup edit yesterday

# Editing yesterday's notes for the category with name "blocking"
$ stup edit @ yesterday -c "blocking"

Editing notes on specific date

# Omitting category option, implying the default one
$ stup edit @ 2020-03-24

# Editing notes saved on March 24th, 2020 for the category with name "blocking"
$ stup edit @ 2020-03-24 -c "blocking"

Copy notes

To copy notes from one date to another use the copy command.

$ stup copy --from today --to tomorrow

The full version of the command:

stup copy --from <copy-from-date> --to <copy-to-date>  -c|--category "<category-name>"

where:

<copy-from-date>: is a date alias (today, yesterday, tomorrow) or a specific date using the format YYYY-MM-DD, for example: 2020-04-18
- this is optional and if omitted defaults to yesterday
<copy-to-date>: is also a date alias (today, yesterday, tomorrow) or a specific date using the format YYYY-MM-DD, for example: 2020-04-18
- this is optional and if omitted defaults to today
-c or --category: is the category option (optional). If omitted, notes will be copied between the default category of the two dates specified
- <category-name>: the name of the category to which the notes will be copied

stup will prompt you for each line to be copied:

stup copy

- Worked on some PRs

>>> Copy this note [y,n,q,a]?:

Examples

Copy notes from yesterday to today, in the default category

$ stup copy

Copy notes from a specific date, to a specific date

$ stup copy --from 2020-01-15 --to 2020-02-01

Copy notes from yesterday to tomorrow in the category "blocking"

$ stup copy --to tomorrow -c blocking

Add a new category

To add a new category to save notes into use the following command.

$ stup add-category --category-name "<category-name>" --category-description "<category-description>"

where:

<category-name>: the name of the category to be created. This is going to be a directory so make sure it's a valid directory name.

<category-description>: the description of this category. Even though this is optionally set, it is highly recommended to be defined. Whenever stup shows your notes, the title of each category will default to the category name if the category doesn't have a description.

# Without a description for category with name mobile
$ stup yesterday

Displaying notes for Friday, April 16th 2020.

>>> mobile

- A note
- Another note
- ...

# With mobile's category description set to "Mobile related notes"

$ stup yesterday

Displaying notes for Friday, April 16th 2020.

>>> Mobile related notes

- A note
- Another note
- ...

Set a category's description

To set a new description or change the existing description of a category use the following command.

$ stup set-category-description --category-name "<category-name>" --category-description "<category-description>"

where:

<category-name>: the name of the category whose description will be set. If you omit this options, you will change the description of your default category.
<category-description>: the description to set

List your categories

To see all your categories use the list-categories command as shown below:

$ stup list-categories

# or the equivalent

$ stup --list-categories

Change the order of categories

To change the order of your categories (affecting the order with which the notes are shown) use the order-categories command as shown below:

$ stup order-categories

# or the equivalent

$ stup --order-categories

This command opens the categories registry file in your editor and you can change the order by moving the category names up and down.

Future work

New features that are on the top of my list for stup:

Add bash completion
Support multiple repositories
Ability to export notes to a file

You can find more information about what is planned to be implemented browsing the GitHub repository's issues labeled as new feature

Contributing

Create an issue describing the purpose of the pull request unless there is one already
Fork the repository ( https://github.com/iridakos/stup/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request