devlog: user guide

about

Your work is more than a series of tasks (although, of course, you do have those). Sometimes the way forward is uncertain — you'll ask questions, prototype, clarify. As you do, you'll come to understand the problem deeply. You'll craft an elegant solution, maybe different from the one you thought initially. That's the challenge and the joy of building software. Devlog is a command-line tool designed for this kind of work.

It is not a project management tool, a bug tracker, a wiki, or a scrum board. Those are great when you need to coordinate, less so for your personal workflow. They add friction to every change, although change is inevitable. Rather than support your process, they constrain it.

Devlog is different. It gives you a space to prioritize tasks, pose questions, and realize solutions. It adapts to change, allowing you to effortlessly update tasks as your understanding evolves. And you can customize it to fit your workflow, not the other way around.

I hope you find it useful.

install

See the installation guide.

create

To create a new repository for your devlogs:

devlog init

By default, devlogs are stored in the directory at $HOME/devlogs. You can choose a different directory by setting the DEVLOG_REPO environment variable.

Examining the repository directory, you'll see a file called 000000001.devlog. This is your first devlog entry. It's just a text file.

edit

To open the most recent devlog file:

devlog edit

The default editor is nano. You can choose a different editor by setting the DEVLOG_EDITOR environment variable. For example:

export DEVLOG_EDITOR=vim

(If you already have the EDITOR environment variable set, that works too!)

Your first devlog entry has already been created. Open it, and you'll see something like:

Welcome to your devlog!

You can add tasks below using this format:
* Use an asterisk (*) for each task you want to complete today.
^ Use a caret symbol (^) for each task that's in progress.
+ Use a plus sign (+) for tasks you completed
- Use a minus sign (-) for tasks that are blocked.

As you work, you can write your questions, thoughts,
and discoveries alongside your tasks.  These will be
stored in your devlog so you can refer to them later.

As you can see, devlog provides a simple way to record tasks. Any line that starts with a *, ^, +, or - is a task. But your devlog is also a place for free-form thoughts. For example:

^ Add method `bar` to class `foo`
    The class is in `lib/utils.rs`.
    The new method is a simple data transformation, so testing should be easy...
    I wonder if I can deprecate method `oldbar` once this is merged?

^ Update library `baz` to version 1.2.3
    Opened the PR, waiting on review.

+ Enable feature flag for cache optimization
    Done!  Checked the system this morning, performance is much better.

As you work, you may realize that some tasks are unnecessary, or maybe you need to add more. That's expected! Just make the changes and keep going.

view

Sometimes, you will want a quick overview of your tasks. "What was I working on before that meeting? What did I need code-reviewed?" To see your current tasks grouped by status:

devlog status

Other times, you will want to see your full devlog entries. "What was the name of that file with the LRU caching logic? What was the name of the branch that added the feature flag?" To see recent devlog entries:

devlog tail

rollover

Over time, your devlog will fill with old tasks and notes. This can be overwhelming. To stay focused on what's important now, you will occasionally run:

devlog rollover

This copies incomplete tasks to a new devlog file. You can do this at the end of the day, to prepare your work for the next day. Or, if you prefer, you can do it at the start of the next day, so you can review your notes from the day before.

Your previous devlog entry still exists! You can always view older entries using devlog tail.

extend

shell scripts

Devlog is designed to be coupled like garden hose with other command-line tools. This allows you to customize it to your workflow.

For example, on many teams you will send a daily "standup" status report to a Slack channel. Suppose you want to report tasks you completed yesterday, tasks you are working on today, and blocked tasks. A simple shell script suffices:

#!/usr/bin/env sh
echo "Yesterday:"
devlog status -b 1 -s done  # completed in yesterday's entry
devlog status -s done       # completed in today's entry

echo "Today":
devlog status -s todo       # todo in today's entry

echo "Blocked:"
devlog status -s blocked    # blocked in today's entry

As another example, suppose you'd like the status report to automatically highlight tasks by status. If you are using vim and have installed the devlog syntax, then you can simply pipe the status output to vim:

devlog status | vim -R -c 'set filetype=devlog' -

That's a lot to type, so you probably want to define an alias in your .bashrc or .zshrc configuration:

alias dls="devlog status | vim -R -c 'set filetype=devlog' -"

hooks

Devlog can be extended through a mechanism called "hooks". A hook is an executable file located in the $DEVLOG_REPO/hooks directory. To enable a hook, make the file executable, like this:

chmod +x $DEVLOG_REPO/hooks/before-edit

The following hooks are available:

Hooks provide a flexible mechanism for integrating devlog with other command-line tools. For example, suppose you want to automatically commit your devlog entries to a git repository. One way to achieve this:

1. Create an after-edit hook to stage the changes in git:

   #!/usr/bin/env sh
   set -e
   repo="$(dirname $(dirname $0))"
   git -C $repo add "$1"

2. Create an after-rollover hook to commit and push the changes to a remote git repository:

   #!/usr/bin/env sh
   set -e
   repo="$(dirname $(dirname $0))"
   git -C $repo add $1
   git -C $repo add $2
   git -C $repo commit -m "Rollover to $(basename $2)"
   git -C $repo fetch
   git -C $repo rebase origin/master
   git -C $repo push

• Automatically synchronizing task status with an external project management tool like JIRA or Trello.
• Customizing the format of the devlog file.
• Grouping tasks based on tags, using a format that you define.

... or anything else that improves your productivity!

library

Devlog is available as a Rust library. Using the library, you can access and parse devlog entries. Please see the library documentation for details.