Opinionated issue tracker built for solo developers.

Info • Install • Usage
Subcommands and flags
Dependencies • License

---

Information

Having a good method of tracking what's finished and what needs to be done is crucial once a project grows large enough. Of course, for team-driven development having a full-featured issue tracker such as GitHub or similar is preferable, but for solo-developers GitHub can feel like an over-engineered solution to a simple problem.

My goal with Brakoll was to create an opinionated issue tracker that is portable between machines and requires no setup, configuration files, special folders, or a specific development environment.

(The name "Brakoll" is derived from the swedish saying "bra koll" - if someone is living their life with structure and purpose, a swedish person may say they have "bra koll".)

The idea for this project was inspired directly by this video.

---

Install

cargo install brakoll

---

Usage

Adding a new issue

The core philosophy of Brakoll is that issues are opened, closed and edited inside the codebase itself. Issues live in the codebase and are not dependent on an internet-connection, or you having to pay a subscription fee at the end of every month. When you want to add something to your issue list you simply type it out in your project, perhaps next to relevant code (tip: create a snippet for this; for example "issue").

// *brakoll - d: fix typo in debug print, p: 10, t: debug, s: closed
fn debug() {
    println!("debugG")
}

• d: description of the issue (obligatory)
• p: priority from 0 to infinity where the highest number takes priority (optional - fallback: 0)
• t: tag (optional - fallback: n/a)
• s: status [ (op)en | (pr)ogress | (cl)osed ] (optional - fallback: open)

The status value can also take abbreviations (op, pr & cl).

Important

• An issue line is any line containing the prefix "*brakoll".
• Everything before the prefix on an issue line is ignored by the parser.
• Everything after the prefix is parsed as metadata.
• Multiple tags are not supported - this is by design, to force clarity when opening issues!

Workflow integration

Here's a way to integrate Brakoll into your neovim config using luasnip:

local ls = require("luasnip")
local s = ls.snippet
local t = ls.text_node
local i = ls.insert_node

return {
    s("issue", {
        t("*brakoll - d: "), i(1),
        t(", p: "), i(2),
        t(", t: "), i(3),
        t(", s: open"),
    }),
}

Here's a way to integrate Brakoll into git using a bash alias:

unalias commit 2>/dev/null
commit() {
    local id="$1"
    brakoll close $id
    brakoll cp $id

    if command -v pbpaste >/dev/null; then
        clip=$(pbpaste)
    elif command -v xclip >/dev/null; then
        clip=$(xclip -o -selection clipboard)
    elif command -v wl-paste >/dev/null; then
        clip=$(wl-paste)
    fi

    git add --all
    git commit -a -m "$clip"
}

My development workflow with Brakoll looks like this:

1. Create a new issue within the codebase.
2. When I want to work on the issue, I set its status to "in progress" either directly in the code or through the CLI.
3. Finish working on the issue.
4. Run command brakoll (with relevant filter flags if necessary) to find its id number.
5. Run bash script commit <id> to close the issue and commit it to git.
6. Run command brakoll summary every once in a while to track my progress.
7. Rinse and repeat.

---

Subcommands and flags

All the issues listed, sorted by priority and status (the current directory is scanned recursively by default):

brakoll

An optional target path can be added (works alongside other flags):

brakoll <relative path>

Filter issues by tag:

brakoll -t <tag>

Filter issues by status:

brakoll -s <status>

Filter issues by description:

brakoll -d <keyword>

Limit scan to shallow depth (i.e. no recursion):

brakoll -r

Summary of all issues:

brakoll summary

Copy issue details to clipboard with formatting: "tag (file:line): desc".
This is to reduce the friction of writing git commit messages manually.

brakoll copy <id>
brakoll cp <id>

Close issue through CLI:

brakoll closed <id>
brakoll close <id>
brakoll cl <id>

Open issue through CLI:

brakoll open <id>
brakoll op <id>

Progress issue through CLI:

brakoll prog <id>
brakoll pr <id>
brakoll progress <id>

Display help and version information:

brakoll help

---

License

This project is licensed under the MIT License.

---

Dependencies

• walkdir
• dirs
• cli-clipboard