sglavoie.com – Tag: Productivity

From a plan to unattended agent runs: how I drive coding agents one session at a time

Sébastien Lavoie — Fri, 09 Oct 2026 16:20:00 -0600

Written with AI: This post was drafted with an AI assistant, working from my notes, code and tools, then reviewed and edited by me. The experiences and opinions are mine, and so are any mistakes.

Introduction

Coding agents got good enough, quickly enough, that the bottleneck in my day moved. It’s no longer typing the code; it’s making sure the code that gets typed is the code I wanted, and that it actually works. The first few weeks went the way I suspect they go for a lot of people: one long conversation per feature, a growing pile of context, and a moment near the end where the agent cheerfully announces it’s done and I discover, ten minutes later, that “done” meant “the parts I remembered are done”.

Trying to resume progress on large features led me to try different frameworks such as Spec Kit from GitHub, OpenSpec, the Kiro IDE, standalone Claude skills and so on. I even built my own harness-agnostic spec-driven framework which I used for a while with (slow) success with GitHub Copilot CLI, Codex and Claude Code. That level of ceremony was right for less capable models, but the picture evolved: the models got better at producing what I wanted without being walked through every step, and I found I needed a different kind of help.

What I needed wasn’t more guidance for the agent. It was less trust in it. Generated code reads fluently, compiles, and is sometimes wrong in ways that only show up later: a concurrency guard that guards nothing, a test that faithfully asserts the bug. Fluency and correctness are uncorrelated, and anyone who has reviewed enough agent output has caught that gap personally. Two problems kept coming back:

Long conversations drift. The further a session goes, the more the early decisions fade, and the agent starts re-solving problems it already solved, or quietly undoing them.
“Done” was decided by the agent. There was no external definition of done that the agent couldn’t argue with, so every finished session still needed me to establish, from scratch, whether it was actually finished.

The second one matters more than it looks. When an agent writes the code, the review doesn’t go away; it moves, and it gets harder, because I’m now checking work I didn’t build the understanding for. Review is the scarce resource. Anything that makes the agent produce more code without making that code cheaper to verify just moves the bottleneck around.

What I ended up with is a small (well… not so small anymore) tool called asl, short for agent session loop. The idea is simple: write a plan, cut it into sessions that each fit comfortably in one fresh conversation, attach to every session a check that a program — not the agent — runs, and then let a runner go through the sessions one at a time while I do something else. This post walks through that pipeline, why each step exists, and what I learned building it.

Why plans, not prompts

Most of the leverage happens before any code is written. A vague prompt to an agent yields a confident implementation of something adjacent to what you wanted; a precise plan yields something much closer. So the pipeline starts with a plain Markdown plan, and with a step whose entire job is to make that plan better before anything runs.

The bar I hold a plan to is that it should be decision-complete: every choice the implementer shouldn’t be making on their own has already been made. The test I use is a slightly hostile question: could two competent implementers follow this plan and end up with meaningfully different behaviour? If the answer is yes, the plan is hiding a decision — about an API, a data format, an error case, a migration order — and the agent will happily make that decision for me, silently, somewhere in the middle of a diff.

It helps to separate facts from decisions. “Which callers use this function?” is something the agent can discover by reading the repository, and it should. “Which of those callers are we willing to break?” is a judgement call, and it stays with me. A good plan records the first kind as discovery and the second kind as an explicit decision.

The step that enforces this is a Claude Code skill called plan-iterate. It reads the plan, assesses how complete it is (scope, interfaces, tests, risks), asks me targeted questions about the weakest areas, and edits my answers back into the file. With --ideal, it first does one research pass over the codebase and describes what the unconstrained ideal version of the change would look like, then ranks the gaps between my plan and that ideal by impact, and asks me to adopt, defer or reject each one. Deferred items get written into the plan so the decision is recorded rather than forgotten.

This is the same instinct behind systematic reviews: it’s cheaper to catch a bad idea on paper than in a diff.

The pipeline, step by step

Here is the whole flow, from a plan to a finished run:

Mermaid source of this diagram

The steps in the middle used to be separate commands I had to remember to run in order. These days a single asl prepare PLAN.md --cwd REPO_ROOT runs split, validation, expansion, baseline and the readiness gate deterministically and, on success, prints the exact asl run command to use next.

Splitting: where to cut

Splitting turns one plan into a directory: a manifest.md listing the sessions and their readiness state, plus one session-<id>.md per session. Each session has a scope, the files it’s expected to touch, a handoff section the agent fills in when it’s done, and a completion contract (more on that below).

Where to cut took me a while to get right. A good session has:

One primary outcome, with evidence that can fail on its own. If I can’t write a check that distinguishes “this session worked” from “this session didn’t”, it isn’t a session yet.
A useful state if the later sessions never run. If the run stops after session 3, sessions 1 to 3 should still leave the codebase in a coherent, reviewable state, not half of a refactor.
Room to work in one fresh context. Context is a split criterion in its own right: the files involved, their size, the instructions that apply and the handoffs from earlier sessions all need to fit, with space left over for the agent to think. It’s much cheaper to re-split before running than to discover forty minutes in that a session can’t hold everything it needs.

Two anti-patterns I now avoid on purpose: splitting implementation from its tests (the test session ends up testing whatever the implementation happened to do), and a “cleanup later” session whose absence would leave the change unsafe. Sessions are ordered by dependency, not by whatever is easiest to edit first: shared contracts and scaffolding before their consumers, additions before removals.

Expanding: the plan is a set of claims

Every path, function signature, command and test name in a plan is a claim about the repository, and plans are often written against a mental model that’s a few commits out of date. Expanding is where the agent reads the actual codebase and checks each of those claims: do these files exist, do these functions have the signatures the plan assumes, is this session secretly three sessions?

The rule that makes this useful is that corrections go into the plan, not into the implementation. Problems get written into a ## Contract Issues section of the session rather than silently patched around. If the agent compensates for a stale fact while implementing, the only record of that decision is the diff, and the next session inherits the stale fact. A session that turns out to be too big can be re-split into child sessions with session-resplit while the rest of the plan is left untouched.

Preflight: the gate

Preflight produces red, yellow and green findings, each with a machine-readable repair hint that names the failing file, the check that failed and the smallest repair. A red or yellow finding blocks the plan from becoming loop-ready, and asl run refuses to start on anything else. When there are findings, a companion skill, plan-preflight-iterate, walks through them with me as a short Q&A and reruns preflight until it’s clean. Because each finding names its smallest repair, that pass only touches what broke.

Preflight also checks the contracts themselves: every expected file either exists or is explicitly marked as new, every command is available, and no placeholder or open decision survived into a session.

One design rule from this part spread to the whole tool: keep authored state separate from derived state. The plan, the sessions, the decisions and the handoffs are authored; the manifest’s readiness flags and status tables are derived, and get rebuilt from the authored files. When the two disagree, the tool pauses rather than picking a winner. A readiness table can always be regenerated; a decision that got silently overwritten can’t.

The point of all this ceremony is to move failures earlier. A missing file discovered during preflight costs a few seconds; the same missing file discovered forty minutes into a run costs a confused agent, a half-finished session and a messy diff.

Completion contracts: who decides what “done” means

This is the part I’d keep if I had to throw everything else away.

Every session file ends with a block like this:

 markdown
 
 
 
## Completion Contract

### Done when

- The `export` command writes one JSON file per project.
- Existing CLI tests still pass.

### Verify

```json
{
 "session": "02",
 "checks": [
 {
 "name": "unit-suite",
 "type": "command",
 "argv": ["python3", "-m", "unittest", "-q"],
 "timeout_seconds": 180
 }
 ]
}
```

“Done when” is for humans (and for the agent to aim at). “Verify” is for the runner: a list of checks — commands to run, files that must exist, patterns that must appear in a file — that the Python runner executes after the agent says it’s finished. If a check fails, the session isn’t complete, no matter how convincing the agent’s summary was. Commands are given as an argument list and run without a shell, so there’s no quoting to get subtly wrong.

Writing these contracts taught me that a check is only as good as what it can falsify. A test suite that would also pass for a plausible wrong implementation isn’t evidence of anything, whoever wrote the code. Agents make that old truth urgent, because they produce plausible wrong implementations at volume. So before I accept a contract, I try to describe one implementation that would be wrong but would still pass it. If that’s easy, the contract needs a sharper check, or the session is claiming more than it can prove.

Three details make this more robust than it sounds:

Baselines. Before the run, asl baseline executes every contract and records what it reports on the unchanged codebase, and preflight won’t let a plan start without that evidence. A check can declare how it should behave before any work happens: a reproducer is expected to fail (proving it actually reaches the thing being changed), while protected behaviour is expected to pass throughout. A protected check that already fails is a broken contract, not a goal — and a reproducer that already passes means the session is either done or testing the wrong thing. Either way, better to know up front than to blame the session for a pre-existing red.
Every check backs a named claim, with a limit. “The focused test passes” says nothing about the database, the deployed service or the code paths it doesn’t exercise. Keeping that limit written next to the check stops a green session from quietly turning into “it works”.
The split between judgement and enforcement. The agent decides how to implement a session. Python decides whether it’s done. The skill the agent runs for each session, session-run, is under a hundred lines of instructions, and that’s on purpose: when the runner launches it, Python already holds the plan lock and has checked readiness, and after the agent returns, Python runs the verification, syncs the progress journal and refreshes readiness. Nothing that matters is left for the model to remember.

That last point turned into a design rule for everything else: anything that must happen is code; only things that require judgement go in a prompt.

What a run looks like

Starting a run looks like this:

bash

asl run ~/.local/share/agent-plans/export-command/ --harness claude

The runner then loops:

Re-read the plan files from disk.
Pick the first pending session.
Start one agent turn, in a fresh context, running /session-run on the plan.
When the turn ends, run the session’s Verify checks.
If they pass, mark the session complete and go back to step 1. If not, put the session back to pending and hand the failing evidence to a repair turn; when the repair budget runs out, stop with a reason.

Re-reading from disk on every turn matters more than it looks. The plan directory is the single source of truth, so I can edit a future session while a run is in progress, and the next turn picks up the change. Nothing about the plan lives only in the runner’s memory.

Fresh context, durable handoffs

Every session starts in a brand new conversation, loaded with only what it needs: the instructions that apply, the plan, its own session file and contract, and the handoffs from the sessions it depends on. That’s the fix for drift: there’s no long transcript for early decisions to fade out of.

It also means the handoff has to carry everything. When a session finishes, the agent fills in its handoff: the files it modified, the key decisions it made, anything blocking the next session, and notes such as why it reran a check. Two optional sections are worth singling out:

Discovered facts record what implementation proved about the plan’s assumptions (“the config loader already caches; no need for a second layer”), so the next session doesn’t spend its context re-researching a settled question.
Open questions hand forward what’s still uncertain, named, instead of leaving it to be rediscovered.

My test for a handoff is blunt: if losing the transcript changes what the next session is allowed to do, the handoff is incomplete. Conversations are disposable; the plan directory is the memory.

Pausing is a feature

Agents fail in loops more than in crashes: rereading the same files, rerunning the same green check, restating the same hypothesis as a “new” fix. Left alone, an unattended run will happily burn an hour that way. So a session that can’t make progress doesn’t keep trying; it pauses, and a pause is a durable state transition with a stable reason, not an abandoned conversation.

The vocabulary is deliberately small and fixed: blocked for a decision only I can make, unsafe when continuing could do damage, verify-failed when the contract didn’t pass after repairs, no-contract or malformed-contract when there’s nothing trustworthy to verify against, a guard violation, and so on. The agent isn’t allowed to invent new reasons. Each pause records what blocked it and the evidence, so the next step is obvious. That makes “why did it stop?” a question with an answer, and it means a retry has to come with something new — a changed hypothesis, a fixed fixture, a decision — rather than the same attempt with more hope.

It took me a while to stop treating pauses as failures. A necessary pause is the system working. A run that pushes through an unresolved decision to keep its completion rate up is worse than one that stops and asks.

The controls I use all the time

--harness picks the agent: Claude Code, Codex or Copilot CLI. The same plan runs on any of them, and I can switch mid-run for the remaining sessions with asl control select-harness. A few other controls I use all the time:

asl control stop-after-current lets the current session finish and then exits cleanly, so the next asl run picks up where it stopped. It’s the polite version of Ctrl-C.
--max-sessions N runs at most N sessions and stops successfully. Useful when I want to look at the first session’s output before trusting the rest.
Pauses with questions. If an agent hits a decision it shouldn’t make alone, the session pauses with reason: blocked. asl questions PLAN_DIR renders the questions, and asl run PLAN_DIR --reply "..." resumes the paused turn with my answer.
--review-harness codex adds a final session where a different agent reviews the finished work and writes its findings to a final-review.md.

A second agent, reviewing cold

That last control deserves a little more space. The reviewer runs on a different harness from the implementer, isn’t allowed to change any code, and reviews cold: from the plan, the contracts and the actual changes, not from the implementer’s account of them. Its job is to find where the change violates the intent, the protected behaviour, the scope or the limits of its own evidence. Its output is structured, not “looks good”: every finding has a severity, the files it points at, an explanation, what “fixed” means, and the checks that would prove it, and the run refuses a review whose summary line and findings don’t agree.

Repairs for its findings are bounded too. Findings are grouped, each group gets a capped number of repair attempts, and the review-and-repair cycles themselves are capped, so a reviewer and an implementer can’t ping-pong forever. The principle I hold myself to on top of that: a repair fixes the finding inside the reviewed boundary, and anything that would change the design goes back to the plan as a new session instead of being absorbed into the fix. The cap limits rework; it never lowers the bar for acceptance.

Having one model check another’s work catches a surprising number of things, but I try not to over-read it. A different model brings different habits for finding failures, not independent evidence. What actually decides acceptance is still the checks, the reproducers and me reading the diff.

When the run ends, it ends with an explicit reason: all-complete, max-sessions or stopped for the happy paths, or a named pause like a failing check or a guard violation. There is no “it just stopped”. And “all-complete” still means the contracts passed, not the change is correct: it’s the point where I go and read the diff, the handoffs and the review, not the point where I merge.

Guardrails, briefly

Once a run is unattended, you need a way to steer it, and the most important distinction I ended up drawing is between advice and enforcement. Telling an agent not to deploy is steering; making sure it can’t reach the deploy credentials is a boundary. A prompt expresses intent, never authority.

Guidance is advice. I can send a running session a note (“prefer the existing date helper over adding a dependency”) and it’s delivered into the conversation. It can shape implementation choices, but it can’t change the session’s scope or its completion contract.
Only a guard enforces. asl control guard add can deny a command (matched as an exact argument prefix and enforced by a per-run PATH shim) or protect a path (compared against a snapshot taken at the start of the turn). A violation rejects the turn and pauses the run. It never rolls anything back, so I can always see exactly what the agent did.

A guard also reports, per harness, whether it is active, degraded or unsupported. Not every agent CLI exposes the same hooks, and I’d rather have a guard say “I can’t enforce this here” than quietly imply it did.

There’s more to supervising a run than this, like a mailbox that lets a running agent ask questions without stopping, and a separate “overseer” that watches runs across projects. They all follow the same rule: an AI that can be argued into an action must never be the guard.

When this is overkill

Most changes don’t need any of this. A local, reversible edit with a test that already covers it needs a boundary, a check and a review — that’s it. I reach for a full plan and an unattended run when a change spans several sessions’ worth of work, when the order of the steps matters, or when I want the run to make progress while I’m doing something else. The pipeline exists so every decision has a home when a change is big enough to need one, not so every typo fix carries maximum ceremony.

A quick way to tell: before handing a task to an agent, can I state the observable outcome and one behaviour that must not change, bound the files involved, name a check that would fail for a plausible wrong implementation, and point to someone (usually me) who can actually absorb the diff? If one of those answers is “no” or “not sure”, the right next step is usually a smaller precursor — reproduce the bug, inventory the callers, write the failing test — rather than the whole change.

Lessons from four months of building it

asl started as a small loop in a script in early June 2026. Four months later it’s about 180,000 lines of standard-library-only Python with about 270,000 lines of tests, built largely by running plans through the tool itself. A few things I’d tell myself at the start:

More tests than code is not a vanity metric. When most of the code is written by agents, the tests are the specification, and they’re what makes the next change safe. There is also a reliability-stress suite that reruns timing-sensitive scenarios under load and across time zones, because “it passed on my machine at 3 p.m.” is not good enough for something that runs unattended overnight.
Make failures early and loud. Every hour spent on preflight, baselines and repair hints has paid itself back many times over in runs that didn’t die halfway.
Promote automation by maturity, not enthusiasm. Almost every piece of asl went through the same ladder: do it by hand while watching, write it down as a checklist or skill, script the deterministic parts, and only then enforce it in the runner. Skipping a rung always produced something that failed in a way I didn’t yet understand.
Turn each run failure into a control. The best features came from runs that went wrong. Agents pausing the whole run for every small question became a live question-and-reply channel; answers that were accepted but never actually read by the agent became receipts proving the agent consumed them. Each one started as a reproducer from a real run and landed as its own reviewed change — never as a quick patch in the middle of the run that exposed it.
Write down the reason for every stop. Every pause and every exit has a stable, named reason. That made the tool scriptable, and made it possible to build a supervisor on top of it at all.
Don’t trust a harness to enforce what it can’t. Supporting three agent CLIs taught me that they differ a lot in what they can actually guarantee, and that the honest answer is to report capabilities instead of assuming them.
Be suspicious of feeling faster. A 2025 randomized trial by METR found experienced open-source maintainers were about 19% slower with early-2025 AI tooling on their own repositories, while believing they’d been faster. That’s not a verdict on today’s tools, but it’s a good reason to judge a workflow by what passes review rather than by how productive a session felt.
Standard library only has been worth it. No dependency upgrades, no virtual environment to break, and the whole thing installs by symlinking a directory with GNU Stow, alongside the rest of my dotfiles.

Conclusion

The biggest change wasn’t any single feature; it was moving “done” out of the agent’s hands. Once every session has a contract that a program checks, the rest follows naturally: sessions can be small and start fresh, runs can be unattended, pauses become information instead of mysteries, a second agent can review the first one’s work, and I can spend my attention on the plan and the review instead of on babysitting a conversation.

If you work with coding agents a lot, my advice is to start there, and to start small. Pick one bounded task you’d normally do yourself in under an hour. Before handing it over, write down what “done” means and one check that would fail if the agent got it plausibly wrong. Then review the diff against that, not against the agent’s summary. If it doesn’t hold up, you’ve lost one session and gained a concrete reason; if it does, you have your first contract.

Resources and references

External links

From this website

Git the gist of it: common commands for a working workflow

Sébastien Lavoie — Sun, 03 Apr 2022 11:21:00 -0500

Introduction

Git, the friend you wish you had met earlier, when organizing files like report 1.pdf, report 2.pdf and report final 1.pdf still made sense somehow. It’s undoubtedly complicated to wrap one’s head around it at first, although there exist some GUIs to make the journey smoother – the best examples that come to mind would include GitKraken and Tower at the top of the list. I have been advised to learn to use Git from the terminal and I would, without flinching, recommend anyone to do the same to really grok this tool and get an intuitive feel for what it does.

Beyond the extraordinary technical prowess that it is, Git can be useful to a broad audience. It’s not good at dealing with large binary files (and Git LFS is not exactly easy to use just yet to cover that case), but for anything involving text that a human can read, it shines – may it be a programming language, some reports written with LaTeX, some diagrams produced with Mermaid or PlantUML, personal notes taken in plain text or in Markdown or the fact that synchronizing changes made to a project is a breeze and allows ones to work from multiple locations and machines.

With platforms like GitHub and GitLab, it is easy to keep a “backup” of projects, which can be either public or private. And despite Git not being awesome with very large files, any smaller binary files like images and PDF files can easily be added to a Git repository, allowing users to keep different versions of these files very easily without using a cloud service such as Dropbox or Google Drive. So even if the original input is not written in a text-friendly manner, the output can still be saved under multiple versions with great details, backed up to different websites and fetched just as conveniently from anywhere else (assuming access has been set up to continue working on a project, or at least one can log in to the website and download files without issue).

Sure, it is not for everyone, but the use cases just described can go a long way. I have used it to practice solving programming challenges, to document all my project at the university, to keep track of preferences and configuration files for my different systems (Linux and macOS) which I’ve described in Managing dotfiles with a Git bare repository, to work on pet programming projects and coding experiments that I keep private, to store code snippets into a growing library for reference purposes, to take notes in the form of “tutorials” or “wiki” (platforms like GitHub and GitLab have a nice wiki feature that renders prose nicely!) for different tasks I need to do infrequently and of course to build this very website in the open (the source code is available on GitHub)! And that is just describing some of my personal use cases without touching on the fact that collaboration within a team is a huge reason to use it!

So with that said, let’s explore some of its functionality, starting with a few tips and tricks, then delving deeper into a real-world workflow and topping it off with more useful commands and configuration settings.

Global and local `.gitignore`

There are files we never care about adding to Git repositories, such as a thumbnail cache file Thumbs.db on Windows or a .DS_Store file storing custom attributes for folders on macOS. Instead of ignoring these kinds of entries in a per-repository .gitignore file which might not contain everything we would like to exclude, it can be simpler and more efficient to use a global .gitignore, which serves the same purpose but for any Git repository regardless of the presence of a .gitignore in that specific repository! In other words, this serves as a permanent list of things to ignore so that there is no need to remember about them later.

The setup is straightforward: create a file ~/.gitignore, fill it as usual with patterns you are sure to want to exclude globally and set a configuration option to use that file – for instance by adding the following to .gitconfig:

git

[core]
 excludesfile = ~/.gitignore

Toptal provides a nice tool on the command-line that can be used to easily exclude patterns. With it, typing gi python >> .gitignore would append a bunch of common patterns to a .gitignore file – in this case, for Python.

Meaningful commit messages with `.gitmessage`

Besides using the excellent Conventional Commits specification to write messages in a format that makes sense to other fellow human beings, using a template for Git commits can help with remembering why commits are made and how they should be structured. There is a configuration setting, commit.template, that can be used to set the default text being displayed when a text editor opens after typing git commit.

The following is the current template I use, which can be saved in a file like ~/.gitmessage:

 
 
 
# [Add/Fix/Remove/Update/Refactor/Document] [summary]


# Why is it necessary? (Bug fix, feature, improvements?)
#-
# How does the change address the issue?
#-
# What side effects does this change have?
#-
# Include a link to the ticket, if any.

Then, this can be added to the config file under the [commit] section like so:

git

[commit]
 template = ~/.gitmessage

All lines starting with a hash symbol (#) will be ignored, so there is no need to manually delete all of this verbose content when saving the commit message. Sweet!

My usual Git workflow

This section depends very much on team standards, if applicable. But in general terms and considering mostly a solo interaction with Git, I like to adhere to the following processes, without taking into account how one would plan, produce diagrams, brainstorm, etc. That shall be the topic of an upcoming post!

Starting a new project

There are different ways to proceed, although I like the simplicity of just creating a new empty repository on GitHub and cloning it on my machine using the SSH protocol, e.g. git clone git@github.com:some/project.git. This has the benefit of automatically setting the main branch and the remote URL, using origin as the default remote. Cloning an empty repository has the same effect as starting with git init, so this also becomes unnecessary.

If I have been experimenting locally first, I would do a git init, commit any changes and then push the new repository on GitHub, either using the great Git integration provided by VS Code or again creating a new repository on GitHub to set the remote URL in order to be able to push local changes, i.e. by doing git remote add origin git@github.com:some/project.git and then pushing to that new URL. To make sure that my default branch is always main (to match the new default on GitHub) and not something like dev or master, I have a Git template lying around that ensures that the first branch created when doing git init will be main. It is as simple as creating the file ~/.git-templates/HEAD with this content:

ref: refs/heads/main

Then, in ~/.gitconfig, the following section is used to read the templates:

git

[init]
 defaultBranch = main
 templateDir = ~/.git-templates

I have this template since before init.defaultBranch was introduced in Git 2.28.0 back in July 2020: now just having the option defaultBranch will do the trick. Still, it’s good to have a templateDir configured for other purposes! Although admittedly, I don’t use them at all and would rather create a custom command to more easily script what I need for each repository: more on this in the section Custom Git sub-commands.

Committing to an existing project

Now that there is some folder set up for Git to track files, it’s time to make changes! I’m a big fan of committing “small and often” because Git is super flexible and updating the history is usually a simple process – unless you have pushed to a remote repository used by other people, in which case being a “force push” type of person won’t make you many friends. May the --force be with you when you push to a private repository where you’re the only contributor, otherwise, it’s good practice to think twice before sending your final changes away as you should not mess up with public history (and depending on how your access is set up within a team, you might not even be able to use the --force flag when pushing on certain branches!).

So what’s the alternative to constantly rewriting history in a harmful way? Well, assuming you have a choice when working alone for instance, there are two main contenders: merge vs rebase. I think neither option is better than the other when used right, but it’s good to know that rebase might create possible headaches because it modifies the Git history while merge might create undesirable noise when used profusely by adding “merge commits”. I use both techniques, but for different purposes.

Being committed

The basic workflow might look like this, with a couple of different options thrown in to cover more scenarios:

 bash
 
 
 
# Check the current state of the repo
git status

# Inspect the changes to commit (before staging)
git diff

# Stage a file to be committed
git add SOME_FILE

# Stage all new/modified files, (i.e., --all)
git add -A

# Stage all modified files (not any new ones, i.e., --update)
git add -u

# Get fancy with adding patches only (part of files)
git add -p

# Undo changes done to a tracked file
git restore -- FILE_NAME

# Inspect staged changes to commit
git diff --staged

# Unstage files
git reset HEAD --

# or just 'git commit' to open a text editor
git commit -m "SOME_MESSAGE"

# See the changes done in the latest commit
git show

# or a specific commit hash from earlier
git show COMMIT_HASH # or ref like HEAD^

# Forgot to add something?
git add SOME_OTHER_FILE
git commit --amend --no-edit

# Want to rephrase the last commit?
git commit --amend

# Tag the latest commit
git tag TAG_NAME

# Tag earlier commit with annotation
git tag -a TAG_NAME COMMIT_HASH -m "MESSAGE"

# Undo a commit, keeping changes in the work tree
git reset HEAD^

# Undo a commit and DO NOT keep changes
git reset --hard HEAD^

# Oops, get back a commit that was "lost"
git reflog # find the relevant commit hash
git cherry-pick COMMIT_HASH # or git checkout COMMIT_HASH

# Explore the repo at an earlier commit
git checkout COMMIT_HASH

# Committed some changes while checking out an old commit?
# Save the changes to a new branch, then potentially merge them back
git switch -c NEW_BRANCH_NAME
git switch OTHER_BRANCH
git merge NEW_BRANCH_NAME

# Undo a merge
git reflog # find the commit hash before the merge
git reset --hard COMMIT_HASH

# Or undo to a known point from a remote branch
git reset --hard origin/main

# Stop tracking a file/directory (remove) but keep it on disk
git rm --cached FILE_OR_DIRECTORY

# Remove stuff that hasn't been committed yet (interactive mode is nice)
# Don't forget about -n for a dry run first!
git clean -i

# Want to undo a change that's already pushed?
# Add a new commit without rewriting history
git revert COMMIT_HASH

# See who did what to which file and when
git blame FILE_NAME

Arguably, basic editing doesn’t require stashing, but that can be helpful for a quick modification, like temporarily saving changes to quickly switch to another branch or pull some remote changes without having to commit first.

 bash
 
 
 
# git stash --help - "Stash the changes in a dirty working directory away"

# Maybe you want to keep changes around without committing
# --include-untracked and --keep-index might be needed!
git stash

# Stash changes with a clearer name/purpose
git stash save "SOME MESSAGE"

# Selectively stash changes (keep specific lines)
git stash save -p

# List existing stashes
git stash list

# See the summary of a stash
git stash show

# See all changes made in a stash (patch)
git stash show -p

# Apply changes from a stash (TAB completion after `apply` is useful)
git stash apply stash@\{SOME_ID\}

# Apply and remove the last stash at the same time
git stash pop

# Remove a single stash
git stash drop stash@\{SOME_ID\}

# Remove all stashes
git stash clear

`rebase`

When working locally with changes that are not yet part of the “permanent” Git history, I like to git rebase very much to clean things up before making a git push, which I like to view as an irrevocable decision. Because I commit small and often, it’s often the case that I end up with a couple of very simple commits which really belong together and should form a bigger commit. While committing a big chunk of code at once avoids having to do any rebase in the first place, it’s also inconvenient to undo a substantial amount of work when you’re experimenting and/or working on an unfamiliar codebase. So in the end, my preference goes towards smaller commits because rebasing is actually fun to do and lets you believe that you came up with brilliant solutions on your first attempt :). That makes for a cleaner Git history for sure, although you will lose some context if you never merge. Meaning, rebasing creates a “linear” history while merging from different branches shows a more complete picture of how a repository really took shape over time. My simple rule of thumb on the matter is this: use rebase to consistently ship meaningful commits (good descriptions, fewer typos, changes chunked logically and precisely, etc.) and use merge to incorporate somewhat larger pieces of history, like a new feature coming from a “feature branch”.

Some common commands I use:

 bash
 
 
 
# git rebase --help - "Reapply commits on top of another base tip"

# Include all commits up to COMMIT_HASH, included
git rebase -i COMMIT_HASH^

# Include most recent commit only
git rebase -i HEAD^

# Include 2 most recent commits
git rebase -i HEAD^^

# Include 3 most recent commits
git rebase -i HEAD~3

# make BRANCH have the history up to COMMIT_OR_BRANCH, included
git rebase COMMIT_OR_BRANCH BRANCH

# Used after resolving a conflict
git rebase --continue

# Reset to where you were before rebasing (move HEAD)
git rebase --abort

# To update the next actions to be taken on the remaining commits
git rebase --edit-todo

There are a bunch of obscure options just like almost any other Git command in existence, but for that there is help available for each command (such as git rebase --help) from the terminal and the trusty Stack Overflow ;).

Sample workflow

In the case of rebase, I enjoy working in this way:

Make small commits, maybe 5 to 10 depending on the complexity of the project – usually as long as a series of commits relates to a single topic whenever possible.
Have a peak at the recent history with git log to have a good idea of what just happened.
Realize that the history can be improved. Find the oldest commit hash (not pushed yet!), take note of it and run git rebase -i COMMIT_HASH^ (with the “hat” ^ at the end to reference the parent of that commit).
This opens up a text editor with some explanations on how to proceed (for more on this, have a look at this great article on Rewriting history). From there, I usually use r to reword, s to squash, e to edit and sometimes f to fixup, besides also re-ordering commits and from time to time deleting one by removing the line entirely.
- r is pretty harmless as it will just show up a new window where the commit message and description can be modified.
- s is more destructive because commits will be “merged” together! No actual change is lost, but if you squash a ton of commits by accident, it will create huge commits and you might want to undo that with reflog before it’s too late (Atlassian has more to say about this in git reflog). The s option is also nice because it keeps all commit messages, so you can edit the final log message as needed without discarding messages.
- e is used to modify the actual source code being committed, maybe to fix a typo or a minor bug after realizing that the test suite no longer passes (assuming you are not programming blindly without tests :)). This can cause some “conflicts” if you change some lines which are also part of other commits in the selection you made originally, so one has to be careful with that. This can also be used in conjunction with git reset HEAD^ to “cancel” the current commit when doing the rebase in order to split it into multiple smaller commits, which can then be “git added” back, followed by a git rebase --continue to keep going.
- f is a quick way of squashing commits together while discarding messages you don’t need. So maybe the last commit has a proper description (“Implemented something…”) and a few commits before that one were just temporary “savepoints” with non-sensical commit messages (things like “testing…” or “new commit”) that were done until you reached a final solution that’s worth committing. So of course in that case the history would be pretty ugly and hard to understand if all commits were kept intact, so these can be added to the latest change which encompasses a working solution as a whole. Just as well, maybe that last commit didn’t have a complete message just yet, so it could also be rewritten with the r prefix.
When individual commits make the rebase stop temporarily (such as when a commit is to be edited with e and waits for changes to be made), then it’s time to do git rebase --continue once the necessary changes are made.
If something goes wrong along the way, there’s always a way back to the place you were right before rebasing with git rebase --abort. It’s worth noting that Git itself will output some useful messages all along so it’s not necessary to remember all of this: it quickly becomes intuitive.

Now, rebase covers the cases where local changes are done in isolation, but for something more imposing or simply to keep track of what happened in which branch, merge remains a powerful ally.

`merge`

So I don’t use merge as much, especially when working solo, but it is undeniably useful and could replace the rebase workflow completely (it might also be demanded by your colleagues anyways!). There’s nothing like a good rebase session to keep things tidy, but a flat history line won’t look attractive on a huge project with many contributors, so merge is there to deal with cleanly integrating changes from different places into some main branch (it could be named differently based on the team workflow of course and there might be more than one “main” branch too). What makes merge incredibly cool is the fact that branches in Git are “cheap”, meaning they can be created very quickly and efficiently, they don’t take space at all, you could have dozens of branches or more and you can incorporate changes from one branch to another with a simple git merge, which is nicer than using git cherry-pick to get multiple commits from one branch into another (for one or two commits though, cherry-pick is handy).

I see rebase more like a cleaning step while merge really shines when dealing with multiple commits between different branches. Even on a simple project when working alone, it has its uses! For example, let’s say we have a repository full of small programming challenges (maybe from HackerRank or LeetCode). We might get stuck on a tricky problem and wouldn’t want to commit an unfinished solution. Also, maybe we would get fed up eventually working on a given challenge and would rather try our luck with a different one. Well, we can always leave changes uncommitted (not very safe as these might be lost!), but that can cause confusion and you might inadvertently end up committing files that have nothing to do with the latest challenge – effectively committing at the same time your unfinished challenge with the one you just completed. There’s always the possibility to git stash individual files to keep them somewhere, but I find working with stashes to be a bit more cumbersome than branches and you might literally forget that you have changes stashed. If you do that a few times, you might not even know which stash is what if you didn’t give them a good name…

Some common commands I use:

 bash
 
 
 
# git merge --help - "Join two or more development histories together"

# Get commits from BRANCH_NAME into the currently checked one
git merge BRANCH_NAME

# Merge one branch into another
git merge SOURCE_BRANCH_NAME DESTINATION_BRANCH_NAME

# Get out of conflicts...
git merge --abort

# Continue after resolving conflicts
git merge --continue

# Keep the "merge commit" in the history
git merge --no-ff BRANCH_NAME

# Set a custom commit message for a "merge commit"
git merge -m "MESSAGE" BRANCH

_{Tip: The command git merge --help describes some nice examples about the whole process of conflict resolution.}

Sample workflow (kinda)

So, instead of risking losing changes like this, creating a new branch with git switch -c BRANCH_NAME and working from there is much easier to confine changes to a specific matter, which we can see like a “feature” that can later be added to the main “trunk”. We can commit unfinished business, switch to a different branch, come back to it later, git reset any old commit to “revert” the history and keep working from a clean state. In any case, there’s always rebase to avoid committing useless stuff, so there’s really no reason to avoid branches.

The merge command will be involved when changes from a “feature branch” (or whatever other purpose you give a branch) are merged into the main branch with git merge BRANCH_NAME. When there are no “merge conflicts” (such as when you work on a totally new file that won’t clash with prior work), this is a seamless workflow where you can just merge as if changes were made in the branch you are on in the first place. There are other instances where bigger changes can be merged successfully in the same way, but it’s interesting to keep track of how you worked on a project, so in this scenario you can always use git merge --no-ff BRANCH_NAME (--no-ff meaning “no fast-forward”) to keep a “merge commit”, which is strictly speaking not needed (because there’s no conflict resolution in the case of a “successful” merge) but can be a helpful reference point when you look back at your Git history two years from now to understand how you worked on something, piecing things together bit by bit.

There’s also an indisputable advantage conferred by the use of branches, which is: you can have plenty of them! So while rebase is nice to use on a given branch, in no way can working on multiple things at once in a single branch and then rebasing all that effort be as straightforward as creating new branches for every new topic that’s being started and then merging it back into a single place of truth. Juggling different concerns in a single branch where you have a few things going on (maybe 2-3 partially implemented features) is far from being a cozy environment and rebasing that kind of work where commits are not even related to each other can become a nightmare in a short amount of time.

Managing branches

So with all that was written earlier, I believe a point was made in favour of using branches. Because branches are such a wonderful feature of Git, here are some more commands I rely on (surprisingly, there aren’t that many for git branch!):

 bash
 
 
 
# git branch --help - "List, create, or delete branches"

# List local branches
git branch

# List only remote branches
git branch -r

# List all branches
git branch -a

# Delete a branch
git branch -d BRANCH_NAME

# Delete a branch forcefully
git branch -D BRANCH_NAME

# Delete a remote branch (doesn't matter if the local branch was deleted)
git push origin --delete REMOTE_NAME/BRANCH_NAME

# Rename a branch
git branch -m BRANCH_NAME NEW_BRANCH_NAME

# Track a specific remote branch
git branch BRANCH_NAME -u UPSTREAM_NAME

# See which branches have been merged or not
git branch --merged
git branch --no-merged

# Switch to the branch last checked out
git checkout -

# Compare changes between branches
git diff BRANCH_ONE..BRANCH_TWO

# Compare a file across branches
git diff BRANCH_ONE:FILE_NAME BRANCH_TWO:FILE_NAME

# See a file from another branch
git show BRANCH_NAME:FILE_NAME

# Get a file from a different branch
git restore --source OTHER_BRANCH_NAME path/to/file.txt

Aliases

While I believe it’s good practice to type complete commands to remember them better, I also tend to use Git aliases for two reasons: because some deeply ingrained concepts don’t need as much reinforcement and because some obscure operations can be made so much more accessible with a pertinent mnemonic device.

Some commands like add just become unforgettable over time, while others – e.g., unstage – just don’t exist yet. Without further ado, here is a list of the aliases I currently rely on when using Git, which comes straight from ~/.gitconfig.

For instance, instead of typing git add, by setting the alias a = add (see below), it is now possible to type git a to get the same result.

git

[alias]
 a = add
 br = branch
 c = commit
 ca = commit --amend
 can = commit --amend --no-edit
 ch = checkout
 d = diff
 ds = diff --staged
 po = push origin
 pos = push --set-upstream origin main
 rc = rebase --continue
 ri = rebase -i
 rl = reflog
 sh = show
 s = status --short
 st = status
 sw = switch
 t = tag
 unstage = reset HEAD --

 ; show changes since last commit
 difflast = diff --cached HEAD^

 ; show last commit
 last = l -1 HEAD

 ; undo last commit
 undo = "!f() { git reset --hard $(git rev-parse \
--abbrev-ref HEAD)@{${1-1}}; }; f"

 l = log

 ; short log
 sl = shortlog

 ; log graph
 lg = l --color --graph --pretty=format:'%Cred%h%Creset \
-%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

 ; log name
 ln = l --name-only

 ; log decorate all
 logda = l --oneline --decorate --graph --all

 ; log stat
 ls = l --stat

 ; log pretty
 lp = log --pretty='%C(yellow)%h %C(cyan)%ad %Cblue%aN%C(auto)%d \
%Creset%s' --date=relative --date-order --graph

At some point, using Git aliases will become second nature, but until then, it can be useful to have a separate terminal alias to list them all (or maybe you forgot the command an alias is using under the hood!). For this, you can set the following alias in a file like ~/.bash_aliases:

 bash
 
alias gitaliases='git config -l | grep alias | sed "s/^alias\.//g"'

# For a fancier version displaying aliases in two columns neatly aligned:
alias gitaliases='git config -l | grep alias | sed "s/^alias\.//g" \
 | sed "s/=/Ω/" | column -t -s "Ω"'

That command will look in the Git configuration, extract all the lines containing “alias” and remove the “alias.” prefix so that you can see all aliases in the form a=add in the case of git add being aliased to git a. If you have a ton of aliases (which is probably a red flag…), finding a specific one is just a matter of doing gitaliases | grep keyword, of course replacing keyword with something else ;).

_{Tip: One can go further to shorten Git commands by shortening git itself! You can put a line such as alias g='git' in ~/.bash_aliases for instance. Now, git add can become g a. Pretty efficient! For more on Bash aliases, you might like to read Aliases: Also Known as Terminal User’s Best Friends.}

This section is really just meant to give a taste of the possibilities that aliases offer. To learn about actual commands and their usage, there is nothing like the official Git docs (there is a short section on Git aliases too).

Custom Git sub-commands

There might be less of a need for custom-made commands to be created when so much can be done with Git alone, but there are cases where these custom additions can shine! As a concrete example, I have been updating this website with what I call my “learning progress” but committing always the same kind of stuff gets boring, so I have created a simple Bash script to automate the process of publishing and committing (the content of the script is of no importance, it is only there to demonstrate that commands other than Git can be called too):

 bash
 
 
 
#!/bin/bash
# Act as custom command `git addlearning` and perform all that follows
# Assumes that `pelican` command is available
cd ~/dev/sglavoie/sglavoie.github.io-source
git add .
git commit -m "Add learning progress"
git push origin main
pelican

cp -r \
 ~/dev/sglavoie/sglavoie.github.io-source/output/* \
 ~/dev/sglavoie/sglavoie.github.io/ && \
 cd ~/dev/sglavoie/sglavoie.github.io && git add .
git commit -m "Add learning progress"
git push origin main
cd ~/dev/sglavoie/sglavoie.github.io-source

It is noteworthy to know that any kind of executable programs can be used, such as Ruby, Python and so on, as long as they are made available in the $PATH. This will be somewhat similar on most UNIX-based system where the PATH variable needs to be exported (usually in a file like .bashrc or .zshrc), for instance:

 bash
 
# $HOME refers to a place like /home/user on Linux or /Users/user on macOS
export PATH="$HOME/dev/git-scripts:$PATH"

On Windows, there are separate instructions to be followed. With that done, there’s also a need to make sure the file is executable, which can be done on the command-line with chmod +x FILENAME_HERE.

Some lesser-known yet incredibly useful commands

`git bisect`

I try to commit working code as often as possible, but sometimes there are just bugs that have flown by and took residence in the codebase a long time ago. In this scenario, there is one tool in the Git tool belt for that very specific use case: git bisect. Working with the binary search algorithm, git bisect searches in a range of commits and by identifying “good” and “bad” commits, will pinpoint exactly where the issue came from in the minimum number of iterations possible. You’ll need sub-commands like start, bad, good and reset at the very least and for more advanced use cases where automatically running a script for each commit is needed, run will do the job. See the docs on git bisect for more.

`git rerere`

I almost never use this in practice, but it can be very useful when working in a large project where similar merge conflicts are likely to occur over time. Git can be “taught” to automatically solve merge conflicts! There are some official docs on this, but I’ve found this Stack Overflow answer to be a more approachable read.

A word on the configuration file

At the very minimum, setting a name and email will be necessary to use Git:

 bash
 
git config --global user.name "Your Name"
git config --global user.email "email@example.com"

Seeing the current configuration can come in handy, too:

bash

git config --global --list

And in the case of this particular command, git config, it can’t be emphasized enough how useful searching through the help page in the terminal will be: git config --help.

I’d be remiss if I didn’t include an example of my own configuration at this point, so here it goes! To make it so that it is convenient to commit this configuration file publicly, some private settings can be “included” from other paths inside the [include] block. For clarity, I’ll show what that file looks like below the main configuration file.

 bash
 
 
 
# This is the content of ~/.gitconfig

[include]
 ; This file can add more information to extend the main configuration.
 ; For example, when inside a directory that match a certain pattern,
 ; we can tell Git to change our name or email (e.g., when committing
 ; with different credentials from a work email)
 path = ~/Dropbox/.custom/.gitconfig
[color]
 branch = auto
 diff = auto
 grep = auto
 interactive = auto
 status = auto
 ui = true
[alias]
 # cut out for brevity, see the section on Aliases
[core]
 editor = nvim
 excludesfile = ~/.gitignore
 pager = diff-so-fancy | less --tabs=4 -RFX
[commit]
 gpgsign = true
 template = ~/.gitmessage
[mergetool "nvim"]
 cmd = nvim $MERGED
[difftool "vscode"]
 cmd = code --wait --diff $LOCAL $REMOTE
[mergetool]
 prompt = false
[color "diff-highlight"]
 oldNormal = red bold
 oldHighlight = red bold 52
 newNormal = green bold
 newHighlight = green bold 22
[color "diff"]
 commit = yellow bold
 frag = magenta bold
 meta = 11
 new = green bold
 old = red bold
 whitespace = red reverse
[push]
 recurseSubmodules = on-demand
[gpg]
 program = gpg2
[filter "lfs"]
 clean = git-lfs clean -- %f
 smudge = git-lfs smudge --skip -- %f
 process = git-lfs filter-process --skip
 required = true
[pull]
 rebase = false
[credential]
 helper = store
[init]
 defaultBranch = main
 templateDir = ~/.git-templates
[diff]
 tool = vscode

The file being referenced/included here, ~/Dropbox/.custom/.gitconfig, looks like this:

 bash
 
 
 
[user]
 email = email@example.com
 name = Your Name
 signingkey = 798034F11B2ADED2
[commit]
 gpgsign = true

# The following block could be used to update credentials when committing
# depending on what directory is opened. So, if you work for COMPANY_NAME
# and the pattern 'COMPANY_NAME' appears in the current working directory,
# then Git can be smart and update your configuration by including
# something like the previous block so that the original email, name,
# signingkey and possibly other config options are overwritten.

; when working at COMPANY_NAME
[includeIf "gitdir:**/COMPANY_NAME/**/.git"]
 path = ~/Dropbox/.custom/.gitconfig-COMPANY_NAME

So this section briefly points out how custom tools like diff-so-fancy can be used, how diff output colors can be customized, how specific code editors like Neovim and VS Code can be opened when committing or dealing with merge conflicts and generally just how the file is meant to be structured.

A lot more on configuring Git can be found in the official documentation on git config.

Conclusion

Being exhaustive when it comes to using Git is definitely not something this article strived to achieve: Git is such a complex piece of software that has been evolving since 2005, when it became a necessity to deal with incoming patches sent to Linus Torvalds to make Linux the fantastic project it has become! There is much, much more to learn, but hopefully this post gives you a slightly different perspective and points the way to a well-rounded journey with the list of references below. Git good!

More resources and references

Websites

Conventional Commits - “A specification for adding human and machine readable meaning to commit messages.”
Git Cheatsheet - “Interactive Git Cheatsheet, categorizing commands based on what they affect.”
Git Immersion - “A guided tour that walks through the fundamentals of Git, inspired by the premise that to know a thing is to do it.”
GitHowTo - “Git How To is a guided tour that walks through the fundamentals of Git, inspired by the premise that to know a thing is to do it.”
GitHub Learning Lab - “With GitHub Learning Lab, grow your skills by completing fun, realistic projects. Get advice and helpful feedback from our friendly Learning Lab bot.”
Learn Git Branching - “An interactive Git visualization tool to educate and challenge!”
Microsoft Learn GitHub modules - “Learn new skills and discover the power of Microsoft products with step-by-step guidance.”
Pro Git Book - “The entire Pro Git book, written by Scott Chacon and Ben Straub and published by Apress, is available here. All content is licensed under the Creative Commons Attribution Non Commercial Share Alike 3.0 license. Print versions of the book are available on Amazon.com.”
Productive Git for Developers - “You will walk through a series of scenarios which you’ll most commonly encounter in your daily work life as a developer.”.
Step-by-step guide to contributing on GitHub - “Have you thought about contributing to an open source project, but you’re too confused (or intimidated) by the process to even try? I’ve been there too!”
Try GitHub - Resources to learn Git: Handbook, cheat sheets, git commands in the browser, etc.

YouTube

CS50 Beyond 2019 - CS50
Git & GitHub Crash Course For Beginners - Traversy Media
Git and GitHub for Beginners - Crash Course - freeCodeCamp.org
Git Tutorial for Beginners: Command-Line Fundamentals (playlist) - Corey Schafer
GitHub Basics Tutorial - How to Use GitHub - freeCodeCamp.org
MIT Missing semester (Version Control) - Git data model - MIT
The Ultimate Git & GitHub Crash Course - Learn to Version Control for Beginners - Laith Harb

Online courses

Git Essential Training (free with free trial) - LinkedIn Learning. “Using a step-by-step approach, author Kevin Skoglund presents the commands that enable efficient code management and reveals the fundamental concepts behind version control systems and the Git architecture. Discover how to track changes to files in a repository, review previous edits, and compare versions of a file; create branches to test new ideas without altering the main project; and merge those changes into the project if they work out.”
Git Started with GitHub - Udacity. “This course is designed to jump right into showing how Git and GitHub work together, focusing on the Git basic workflow. Students can expect to learn the minimum needed to start using Git in about 30 minutes.”
How to Use Git and GitHub - Udacity. “This course, built with input from GitHub, will introduce the basics of using version control by focusing on a particular version control system called Git and a collaboration platform called GitHub.”
Short and Sweet: Get Started with Git and GitHub Right Now - Udemy. “In just 30 minutes, this “Short and Sweet” course covers the essential ideas you need to move forward, without a lot of filler. At the end of the course, you’ll be able to set up a GitHub account, install Git, create and configure new Git and GitHub repositories, create a change history for your software projects, and publish your software projects to GitHub.”
The Ultimate GIT 5-day Challenge - Udacity. “A quick way to determine if working with GIT is something you want to learn more about. This course takes us step-by-step through some basic GIT operations. The course will not dive too deep, and takes small steps on each of five days. As we continue through the course, we learn a basic, single-person workflow that could allow anyone to store files at GitHub or BitBucket.”
Version Control with Git - Coursera. “In this course, you will not learn everything there is to know about Git, but you will build a strong conceptual understanding of the technology, and afterward will be able to confidently dig deeper on any topic that interests you.”
Introduction to Git and Github - Coursera. Offered by Google. “In this course, you’ll learn how to keep track of the different versions of your code and configuration files using a popular version control system (VCS) called Git. We’ll also go through how to setup an account with a service called GitHub so that you can create your very own remote repositories to store your code and configuration.”

References for this article

git rerere - git-scm.
35+ Git Commands List Every Programmer Should Know - loginradius.
Binary search algorithm - Wikipedia.
Gitignore - Toptal.
HackerRank.
LeetCode.
Rewriting history - Atlassian.
The new Git default branch name - GitLab.
What is git-rerere and how does it work? - Stack Overflow.

Using dmenu to Optimize Common Tasks

Sébastien Lavoie — Sun, 10 Nov 2019 09:02:00 -0600

Introduction

dmenu is one of those tools that look a little unimpressive at first but can accomplish so much! It’s a program that you can use to receive any output redirected from other programs (through pipes in the terminal, the symbol |) and treat that output so that it can pop up within a simple menu to make it available for execution. If you want to know more about other fantastic tools from suckless.org, I went over some of them before, such as the st terminal and slock, a dead simple screen locker.

Any Simple Example?

You bet! Before diving in with how to install it and some more concrete examples, you could give dmenu a go with a simple command such as the following (assuming the program is installed on your machine).

bash

ls | dmenu

This will effectively “pipe” the output of ls into dmenu and a menu like the following would appear (by default, it shows as a thin stripe at the top covering the width of the screen):

If you start typing, the displayed list will be filtered down like so:

You can also switch to the next item to be highlighted by typing Ctrl + n, to the previous item by typing Ctrl + p and exit by reaching for the Escape key. For now, if you type Enter once your desired selection is highlighted, the selection will be outputted to the terminal and that will be the end of it. Let’s convert this into a practical thing, then.

Keeping the same output as before which only contained directories, we could open a file manager (here, I’m going with pcmanfm) and do something like this (bear with me, the explanation follows!):

 bash
 
ls | dmenu -l 5 | xargs -I {} pcmanfm "{}"

This is now a fully functional example, albeit its practicality is debatable. What will happen, exactly?

First, ls will output a list of directories in the current working directory. That is, the following would be printed in the terminal without any piping:

Desktop Downloads Learning Pictures Public Templates virtualbox_vms
Documents Dropbox Music Programming SortOut Videos

When we pipe this into dmenu, we will get a menu with all that output nicely formatted vertically, which is what the -l 5 options does (here, we want only 5 lines to show). We will see a maximum of 5 items as this is the value we passed to the -l option:

We can still start typing a word that doesn’t show up in this list like Mu and we will see that this list is filtered to only include the matching directory Music even though we couldn’t see it before since we limited our results to 5 items. We could also use the same technique with Ctrl + n and Ctrl + p to cycle between the elements.

Up to this point, we are getting our selection outputted to the terminal. Next, we pipe it into xargs, which will allow us to specify a command to which we will pass our result (what is printed to the terminal) as an argument (we could make use of more arguments depending on the output we get, but let’s start simple). The -I {} option will make it possible to “quote” our result so it is read as a single argument and properly escaped. This means that without this option, if we have spaces or other special characters in the argument (such as a folder called My Music), it would try to pass each word as a new argument to pcmanfm, trying to open both My and Music directories at once.

We are representing our output as {} and when we quote it with pcmanfm "{}", spaces are interpreted without any trouble. If we wanted to use various arguments instead, we could try something like this:

 bash
 
echo "file1.txt file2.txt\nfile3.txt file4.txt" | dmenu -l 2 | xargs cat

The part before the first pipe character will print to the terminal those two lines:

file1.txt file2.txt
file3.txt file4.txt

When we pipe this into dmenu -l 2, we will get this menu:

Typing Enter on one of the highlighted items would then trigger xargs to pass the content literally to cat as arguments, which would then print to the terminal the content of both file1.txt and file2.txt (the first line containing two arguments for cat) or the content of both file3.txt and file4.txt (the second line also containing two arguments for cat) in succession.

Now that we got our feet wet with what dmenu does (displays a menu), we might want to install it.

How do You Install It?

In Manjaro Linux, it comes with i3 if you use that flavor of the distribution and can be opened by pressing the modifier key (either Super/Windows key or Alt key) along with the letter d, as in the shortcut mod + d, or by typing dmenu_run in a terminal, which will present a list of installed applications to launch. Otherwise:

Debian-based (such as Ubuntu)

bash

sudo apt install dmenu

Arch-based (such as Manjaro)

bash

pacman -Syu dmenu

You can also install it from your distribution’s package manager if available or from source.

Useful Real-World Examples

Here are a couple of ways I like to use dmenu to open a menu with a list of:

cheat sheets;
filesystem paths;
most used documents;
documents & books I read at the university;
custom scripts I want to run in the background.

Here are a few screenshots of how it currently looks like in my daily usage so you get a better idea.

Cheat sheets

University shortcuts

File manager shortcuts

So, how does that all work? As a starting point, all of those menus are launched through a specific keyboard shortcut that uses a mnemonic for each one (mod being the “modifier” key on i3, which is set to Super/Windows):

mod + Alt + c: cheat sheets;
mod + Alt + d: documents;
mod + Alt + f: file manager;
mod + Alt + s: scripts;
mod + Alt + u: university.

Let’s take the cheat sheets example, which is a bit more interesting since it launches different applications.

Setting Up a Custom Command

Configuration for i3 (bind a keyboard shortcut)

Here, I’m using i3 to set a keyboard shortcut to run a specific command, but this will be a similar experience on other window managers and desktop environments.

 bash
 
 
 
# i3config file
# The backslash at the end of the line allows us
# to split the line to increase readability

## Cheatsheets

bindsym $mod+Mod1+c exec --no-startup-id \
cat path/to/cheatsheets.conf \
| dmenu -l 30 | sed 's/.* \+//' | sh

You would usually be able to launch a custom command from your environment through a keyboard shortcut. If passing a direct command such as the above one isn’t an option, you can always store it in a Bash script and run that Bash script instead as the designated custom command. The script would then contain the following:

 bash
 
#!/bin/bash

## Cheatsheets
cat path/to/cheatsheets.conf \
| dmenu -l 30 | sed 's/.* \+//' | sh

As far as i3 is concerned, that’s all you need to do. You would need to reload the configuration file (by default: i3config) where the previous bindsym command has been set up to apply the changes (default shortcut to reload: mod + Shift + c).

Configuration for cheatsheets.conf

The content of this file is literally what will be shown when dmenu opens it. An excerpt:

 
#---------- Cheat Sheets -------------------------------------------------------
bash st -e nvim path/to/bash.sh
git zathura path/to/github.pdf
vimwiki firefox path/to/vimwiki.html

Here, we have set a maximum of 30 lines to be displayed (-l 30). What follows after an element has been selected with dmenu allows us to parse the content of the line and retrieve only the command we are interested in with sed before passing that filtered content around to sh to execute it as a shell command. With more complex commands requiring multiples arguments to be received, we could add one more pipe between sed and sh like this (or with xargs -I {} to avoid problems with spaces):

 bash
 
cat path/to/cheatsheets.conf \
| dmenu -l 30 | sed 's/.* \+//' | xargs -r | sh

If the line we want to run only includes a path to a file as in:

myshortcut path/to/file.pdf

We could instead pipe it into an external command of choice if the same program applies to all items presented in the menu, say Firefox:

 bash
 
cat path/to/file.conf \
| dmenu -l 30 | sed 's/.* \+//' | xargs -I {} firefox "{}"

What’s nice with the way pipes work in a Unix-like system is that we can chain harmless commands until the very end so they will simply be printed to the terminal. In this example, if we want to see how to filter our lines before running a command, we can do so as follow.

Pipe 1

 bash
 
cat path/to/cheatsheets.conf \
| dmenu -l 30

If you remember from the menu we saw earlier, there’s a shortcut to open a cheat sheet for Git. Let’s say we selected that one with dmenu. Because our command isn’t doing anything with the result, it will be outputted to the terminal like so (just like in the excerpt of cheatsheets.conf):

bash

git zathura path/to/github.pdf

What sed does here is to cut everything from the beginning of the line up to where the command starts (that’s where we find zathura, which is a powerful document viewer), because we need to isolate that part of the line so it looks like a shell command we could run on its own. Let’s add a new pipe to our command and see what sed does with it*.

* _{We could have used other tools to parse the string like awk, grep, cut, etc.}

Pipe 2

 bash
 
cat path/to/cheatsheets.conf \
| dmenu -l 30 | sed 's/.* \+//'

If we select the same item as before with dmenu to illustrate more clearly what this new addition does, we will get this output:

bash

zathura path/to/github.pdf

If we were to type this in the terminal (assuming the file exists and zathura is installed!), that would do the trick and it would open with the specified document viewer. Pipe 2 and subsequent pipes before we execute something is where the filtering magic happen. In short:

Everything before | dmenu is how our input will look like when we run dmenu;
Everything after | dmenu [options here] | is what we need to do to our input so that it is converted into a working shell command;
Finally, what comes after the last pipe (either xargs, sh or a combination of both) is our way to redirect our string to the shell so it can be executed.

Once we are visually satisfied with how our command is supposed to look like (it has to be something that works when typed directly in the terminal), the next step is to pipe it again so it can be executed.

Pipe 3

 bash
 
cat path/to/cheatsheets.conf \
| dmenu -l 30 | sed 's/.* \+//' | sh

There we go, the command is launched. If we keep the same simple syntax in all of our .conf files —or whatever extension we choose— where the content of our menus is stored in plain text, we can quickly and painlessly create keyboard shortcuts to run custom lists of commands that can be edited on the fly. Once our shortcuts are active, it’s only a matter of editing one of those .conf files and automatically our lists will be up-to-date when we trigger the shortcut again.

Running a Custom Script

If we want to run custom scripts, we need to indicate a command that would work in the terminal, such as python myscrypt.py or ./myscript.sh. When it comes to shell scripts, we have to make sure they are executable. We can do so through a file manager or within the terminal like this:

bash

chmod +x path/to/script.sh

This will add the necessary permissions for the user to execute the script. As we already know, we would then need to add a keyboard shortcut to launch our custom menu and store our command in a file like scripts.conf that would contain the following:

#---------- scripts.conf -------------------------------------------------------
myscript script.sh

And that’s all there is to know to get piping with dmenu! You may also find this video from Luke Smith on YouTube to be quite helpful as well, which is where the inspiration for this post came from. He also posted a complementary video about adding prompts to your commands which is a nice way to add interactivity to your scripts!

Chaining dmenu prompts

Another useful scenario is when you want to take a specific action based on the output of a previous command. For instance, let’s say you want to read a book but when you choose a pdf with dmenu, you want to be prompted for which reader to use while you want to let the system choose the default application for other types of files (e.g. epub or mobi). This could be achieved with a script similar to the following one:

 bash
 
 
 
#!/bin/bash
FILE=`find ~/Documents/calibre_library -type f -iname "*.pdf" -o \
 -iname "*.epub" -o -iname "*.mobi" | dmenu -l 30`

if [[ "$FILE" == *.pdf ]]
then
 READER=`echo -e "zathura\natril" | dmenu -i -p "Which reader?"`
 $READER "$FILE"
else
 xdg-open "$FILE"
fi

Here’s what’s happening:

We find all the files (-type f)
in the directory ~/Documents/calibre_library
that match a pattern that’s case-insensitive with -iname (here, ending in either pdf, mobi or epub)
matching one file at a time (-o can be interpreted to mean “only” and will keep searching if the previous file extension was not matched)
then presenting 30 lines (-l 30) of results at a time with dmenu
then, if the file is a PDF, prompts whether to use atril or zathura as the file reader and open with the chosen program
otherwise, open the file with the default application.

Customize the Look of dmenu

As they say, “beauty is in the eye of the beholder”. If you would rather make some changes to how dmenu look, you can. dmenu will be searching for the configuration file located at ~/.dmenurc, which could contain something as put below (with this configuration, it will look like the screenshots shown previously):

 bash
 
 
 
#
# ~/.dmenurc
#

# define the font for dmenu to be used
DMENU_FN="NotoSans-10.5"

# background colour for unselected menu-items
DMENU_NB="#161925"

# textcolour for unselected menu-items
DMENU_NF="#fdfffc"

# background colour for selected menu-items
DMENU_SB="#235789"

# textcolour for selected menu-items
DMENU_SF="#fdfffc"

# command for the terminal application to be used:
TERMINAL_CMD="st -e"

# export our variables
DMENU_OPTIONS="-fn $DMENU_FN -nb $DMENU_NB -nf $DMENU_NF -sf $DMENU_SF -sb $DMENU_SB"

Conclusion

Hopefully this introduction to what dmenu has to offer gave you some ideas. I hope you’ll find many ways to adapt the examples so you can benefit from this amazing tool. You can find more configuration details in my dotfiles on GitHub for anything related to i3, dmenu, zathura, st, slock and many more useful programs.

Have a good time automating your digital life!

Black: A Python Formatter to Brighten Your Workflow

Sébastien Lavoie — Sat, 13 Jul 2019 13:10:00 -0500

What is Black?

From its GitHub repository:

Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

Black will take less than ideal code and will automatically reformat it according to the PEP-8 style guide. It will take care of many things, including the following (taken in that order from README.md in Black’s repo):

Wrapping lines properly by shortening as much as possible single statements;
Break long lines;
Remove superfluous empty lines;
Take care of adding trailing commas where necessary;
Convert single quotes (') to double quotes (");
Convert numeric literals to lowercase (0XAB to 0xAB);
Superfluous parentheses are removed;
Split call chains on different lines;
Works from the terminal and support many code editor integrations (Emacs, Vim, VS Code, Sublime, etc.).

Now that it’s clear why it can be a good idea to use it, let’s see how it works with Vim and the terminal.

How to use it?

First, we need to install it using Python 3.6.0+:

bash

$ pip install black

That’s it!

Use it from the terminal

In its simplest invocation, we can use Black by specifying a file or a directory by typing:

bash

$ black path_to_file_or_directory

It doesn’t come with many options as its goal is to automatically format code consistently, but you can find out more about this tool in the following way:

bash

$ black --help

Use it with Vim

Using Black as part of your workflow in a code editor is where I believe it really shines, because you can see almost in real-time when you make a formatting mistake, which will help down the road in committing less sins.

Integrating Black with Vim or Neovim is quick and painless, adding a simple line in your .vimrc or init.vim file. You can also proceed to do a manual installation without a plugin manager as explained in the GitHub repository.

With vim-plug:

 vim
 
Plug 'python/black'

With Vundle:

 vim
 
Plugin 'python/black'

Once the plugin is installed, it may well be convenient to automatically format Python files when saving the buffer, which can be accomplished by adding the following line to the configuration file:

 vim
 
autocmd BufWritePre *.py execute ':Black'

By default, Black works surprisingly well on its own. I only went ahead and changed the default line length from 88 to 79 characters by also adding this line:

 vim
 
let g:black_linelength = 79 " default is 88

Finally, it’s worth noting you can update Black at any point from the terminal with pip and you can also do it directly from within Vim/Neovim with this command:

 vim
 
:BlackUpgrade

Vim will then output something along those lines:

Upgrading Black with pip…

DONE! You are all set, thanks for waiting

Any example?

Taking a random Python 3.6+ code sample, we could originally have something like this (hopefully not):

 python
 
 
 
 for source in data_sources :


 # Retrieve a list of all matching log files in `source`
 log_files=glob.glob( f'{source}/{LOG_NAME}*' )
 if log_files == [ ]:
 print(f'\nThere is no log file to delete in {source}.')
 continue
 else :
 print(f'Log files in {source}:')
 for log_file in log_files:
 if (ARGUMENTS.remind): REMINDER_IS_SET = True
 print(
 log_file
 )
 message = (
 '\nDo you want to delete log files ' 'for this source? (y/n) '
 )
 if (user_says_yes( message = message )) :
 for log_file in log_files: os.remove(log_file)
 print(
 'Log files deleted.'
 )
 continue
 else : continue
 print( 'Exiting script...' )
 sys. exit(0)

Running Black, we will get something that’s quite a bit more palatable:

 python
 
 
 
 for source in data_sources:

 # Retrieve a list of all matching log files in `source`
 log_files = glob.glob(f"{source}/{LOG_NAME}*")
 if log_files == []:
 print(f"\nThere is no log file to delete in {source}.")
 continue
 else:
 print(f"Log files in {source}:")
 for log_file in log_files:
 if ARGUMENTS.remind:
 REMINDER_IS_SET = True
 print(log_file)
 message = (
 "\nDo you want to delete log files " "for this source? (y/n) "
 )
 if user_says_yes(message=message):
 for log_file in log_files:
 os.remove(log_file)
 print("Log files deleted.")
 continue
 else:
 continue
 print("Exiting script...")
 sys.exit(0)

Conclusion

I think the results speak for themselves: enforcing a style with a tool like Black is definitely useful to avoid arguments about conflicting coding styles. It lets you focus on what matters instead: being productive while providing value to the world.

fzf - A Fuzzy Finder to Accomplish Anything

Sébastien Lavoie — Fri, 24 May 2019 10:56:00 -0500

Introduction

I know people who make such a mess when not organizing their files and directories appropriately on their system, they would benefit greatly from fzf.

What is fzf?

From the official GitHub page:

fzf is a general-purpose command-line fuzzy finder. It’s an interactive Unix filter for command-line that can be used with any list; files, command history, processes, hostnames, bookmarks, git commits, etc.

Terminal aliases

One of the main uses of fzf is from the terminal. Being so flexible to use, it can be combined with all kinds of commands with the help of pipes (|) to bend it to your desires. Here are some aliases I am currently using that undoubtedly improve my terminal workflow.

 bash
 
##### Functions

# Select a configuration file with fzf and open it with Neovim
conf() { du -a ~/.dotfiles/* ~/.config/* | awk '{print $2}' | fzf | xargs -r nvim ;}

# Select a file from current folder and recursively with fzf and open it with Neovim
se() { du -a ./* | awk '{print $2}' | fzf | xargs -r nvim ;}

# Select a file recursively from university folder with fzf and open it with default app
sc() { du -a ~/Dropbox/university/* | awk '{print $2}' | fzf | xargs -r xdg-open ;}

The first alias, conf (short for configuration), allows to search only within the two folders specified for configuration files, which makes it pop almost instantaneously since it doesn’t have to scan files scattered anywhere else. You can then type anything that partially matches a file path and even include slashes (/) in your match if you know in which directories to look. You can then type Enter to open the file with your favorite text editor (here set to nvim) or type CTRL + c to abort the command.

The other aliases work in a similar fashion. se (short for search) will simply search recursively for any kind of files in the current directory and open the selected file in a text editor. Of course, certain file types can be excluded and everything else can be tweaked with more piping power. In the case of the third alias, sc (short for school), it will also search recursively for any kind of file in the university folder and will open it with the default application set to open that kind of file (video, image, text, PDF, etc.).

Vim/Neovim integration

Using Vim-Plug from the same author as fzf is as easy as adding the following to Vim/Neovim’s configuration file. First, we make sure that fzf is available on the system and install it if it’s not. Then, we install the fzf.vim plugin to integrate fzf in Vim and optionally, we may configure more options so that fzf can be used more optimally, which can be found on the GitHub plugin page.

 vim
 
 
 
Plug 'junegunn/fzf', { 'dir': $HOME . '/.fzf', 'do': './install --all' }
Plug 'junegunn/fzf.vim'

""""" [ FZF ]
" Allows fzf to ignore patterns in .gitignore
let $FZF_DEFAULT_COMMAND = 'ag -g ""'

" Mapping selecting mappings
nmap <leader><tab> <plug>(fzf-maps-n)
xmap <leader><tab> <plug>(fzf-maps-x)
omap <leader><tab> <plug>(fzf-maps-o)

" Insert mode completion
imap <c-x><c-k> <plug>(fzf-complete-word)
imap <c-x><c-f> <plug>(fzf-complete-path)
imap <c-x><c-j> <plug>(fzf-complete-file-ag)
imap <c-x><c-l> <plug>(fzf-complete-line)

" Advanced customization using autoload functions
" (expand word completing window)
inoremap <expr> <c-x><c-k> fzf#vim#complete#word({'left': '20%'})

" Make use of fzf command instead of CtrlP
map <C-p> :FZF<cr>
""" [ / FZF ]

Working with Neovim

fzf really shines when used with Neovim as it is extremely fast, especially when configured with The Silver Searcher which deserves its own article. It integrates with core functionality of Vim and makes it easy to find what you are looking for.

From the above configuration, for instance:

 vim
 
nmap <leader><tab> <plug>(fzf-maps-n)

This allows to search for existing mappings and commands, which can be faster than diving in the help pages when looking for a quick reference.

This one in insert mode is very handy:

 vim
 
imap <c-x><c-k> <plug>(fzf-complete-word)

Without affecting keyword completion with CTRL + n and CTRL + p (unless you have set complete+=k in your configuration file), you can complete words from a custom dictionary of your choice with CTRL + x CTRL + k. The window that appears can be moved and resized, which is what is happening here:

 vim
 
inoremap <expr> <c-x><c-k> fzf#vim#complete#word({'left': '20%'})

In the same way, file paths can be completed from the current working directory CTRL + x CTRL + f and existing lines can be quickly inserted with CTRL + x CTRL + l.

Finally, I use fzf to open any file quickly from the working directory inside Neovim with the mapping CTRL + p, which replaces the CtrlP plugin and can work much faster on larger codebases.

Conclusion

There is much more that can be done with it and I am barely scratching the surface here. Luke Smith shared a great video that will complement the information from this post nicely with a more technical approach. Highly recommended to see more practical ways to use this superb piece of software!

Luke Smith also makes a strong point of combining fzf with dmenu, a tool that I described succinctly in a previous article.

Suckless: Minimalist Tools That Work Great

Sébastien Lavoie — Sun, 12 May 2019 22:50:00 -0500

What are Suckless tools?

From the official website:

Home of dwm, dmenu and other quality software with a focus on simplicity, clarity, and frugality.

There are also other incredible pieces of software that are worth mentioning, including st.

Here, I will only go over the tools I use frequently, but keep in mind that everything from Suckless… Sucks less.

st — Simple Terminal

I did not know what to expect from this terminal and I found it delivers what I need! Configuring it is quite different than other terminals like Konsole or GNOME Terminal: you just edit a text file and compile the software before you can even use it. It may seem tedious at first, but compiling such a small piece of software is very fast and it needs to be done on seldom occasions when you may want to adjust a setting.

I have experienced rendering issues when scaling the text with other terminals (including Konsole), where some weird flickering would happen at certain font sizes. Simple Terminal just works without hassle. It doesn’t have much bells and whistles out of the box, but it can be patched to extend its functionality if you know what you are doing. I don’t, so my compiled version remains pretty basic although I must say I like the simplicity of it very much.

Configuration

I didn’t have to adapt the configuration file very much. I ended up changing mainly the following lines:

 cpp
 
 
 
static char *font = "Consolas:pixelsize=18:antialias=true:autohint=true";

static char *shell = "/bin/zsh";

/* Terminal colors (16 first used in escape sequence) */
static const char *colorname[] = {

 /* 8 normal colors */
 [0] = "#1c1c1c", /* black */
 [1] = "#ff005b", /* red */
 [2] = "#70e502", /* green */
 [3] = "#fcdd11", /* yellow */
 [4] = "#00a0ea", /* blue */
 [5] = "#bd1efc", /* magenta */
 [6] = "#14ecfc", /* cyan */
 [7] = "#ededed", /* white */

 /* 8 bright colors */
 [8] = "#666666", /* black */
 [9] = "#ff00a0", /* red */
 [10] = "#5dff00", /* green */
 [11] = "#ff9f00", /* yellow */
 [12] = "#71a9fc", /* blue */
 [13] = "#d571fc", /* magenta */
 [14] = "#6cf2fc", /* cyan */
 [15] = "#fcfcfc", /* white */

 /* special colors */
 [256] = "#0a0500", /* background */
 [257] = "#e0e0e0", /* foreground */
};

/*
 * Default colors (colorname index)
 * foreground, background, cursor
 */
unsigned int defaultfg = 257;
unsigned int defaultbg = 256;
static unsigned int defaultcs = 257;
static unsigned int defaultrcs = 256;

/*
 * Colors used, when the specific fg == defaultfg. So in reverse mode this
 * will reverse too. Another logic would only make the simple feature too
 * complex.
 */
static unsigned int defaultitalic = 7;
static unsigned int defaultunderline = 7;

/*
 * Default shape of cursor
 * 2: Block ("█")
 * 4: Underline ("_")
 * 6: Bar ("|")
 * 7: Snowman ("☃")
 */
static unsigned int cursorshape = 2;

/*
 * Default columns and rows numbers
 */

static unsigned int cols = 80;
static unsigned int rows = 24;

dmenu

dmenu can be configured in the same way as Simple Terminal by editing a text file and compiling the software. I like to use many keyboard shortcuts, but I find that for launching applications I don’t use that often or to launch custom Bash or Python scripts on the fly, nothing beats the simplicity of dmenu.

Configuration

This one is very easy to configure and doesn’t really require any attention at all besides defining where you want it to appear on the screen and what colors you prefer. Here are some smalls changes I made to the configuration in config.h before compiling it:

 cpp
 
 
 
static int topbar = 1; /* -b option; if 0, dmenu appears at bottom */
/* -fn option overrides fonts[0]; default X11 font or font set */
static const char *fonts[] = {
	"Consolas:size=12"
};
static const char *prompt = NULL; /* -p option; prompt to the left of input field */
static const char *colors[SchemeLast][2] = {
	/* fg bg */
	[SchemeNorm] = { "#D8D8D8", "#000000" },
	[SchemeSel] = { "#000000", "#ff7400" },
	[SchemeOut] = { "#000000", "#00ffff" },
};
/* -l option; if nonzero, dmenu uses vertical list with given number of lines */
static unsigned int lines = 0;

/*
 * Characters not considered part of a word while deleting words
 * for example: " /?\"&[]"
 */
static const char worddelimiters[] = " ";

slock

What can be said about slock? It just works and never gets in your way. Set it and really forget it. From the official page:

This is the simplest X screen locker we are aware of.

Again, its simplicity is charming and nothing really needs to be changed in config.h apart from colors and setting the correct username and group name to lock and unlock the screen.

Conclusion

This was a lighting fast overview of some of the tools I now use on a daily basis. Suckless tools caught my attention and kept it! They offer other specialized software like a web browser, a tool for presentation from the terminal, IRC client and others… but the ones described here are really those which I now can’t live without.

I was originally inspired to seek out those tools thanks to Luke Smith, a fantastic YouTuber.

Tag Navigation in Vim

Sébastien Lavoie — Fri, 19 Apr 2019 17:52:00 -0500

Navigate inside the current buffer

There is a command gd that stands for Goto local Declaration. It is quite useful when looking for a variable inside the current buffer as it allows to jump to where it is declared when the variable is under the cursor. Using that command, you can also find where a function is declared and it will find the first occurrence in the current function. If looking for the first occurrence in the buffer, gD (Goto global Declaration) will do the trick. You can jump back and forth to where you were with the commands Ctrl + O (older position) and Ctrl + I (newer position) in normal mode.

Navigate inside all buffers within the current project

To be able to jump between buffers and go back to the origin of a declaration when it is imported in the current module, generating tags comes in very handy as it allows you to use the command Ctrl + ] to jump to a tag, just like when using the help pages in Vim.

To make this work, we can conveniently use ctags. First, we need to make sure it’s installed on the system as follow:

Debian/Ubuntu

bash

sudo apt-get install ctags

bash

sudo apt-get install exuberant-ctags

OS X

bash

brew install ctags

You can put the following command in your configuration file to be able to generate the necessary tags inside Vim by typing MakeTags in command mode:

 vim
 
command! MakeTags !ctags -R .

This will make it easy to remember how to do it. After that, open an existing project in its root directory and use this newly created MakeTags command to generate the tags. This will create a file named tags in the current working directory*. Now, you will be able to open any file inside your project and jump to all the available declarations with Ctrl + ].

* _{Note: This will create tags recursively from the current working directory, not from the path matching the current buffer.}

If you go to a tag that leads you a few declarations away in one file or another, you can come back with Ctrl + T. Here is a clear explanation from Vim’s help:

The most obvious way to use this is while browsing through the call graph of
a program. Consider the following call graph:

	main ---> FuncA ---> FuncC
	 ---> FuncB

(Explanation: main calls FuncA and FuncB; FuncA calls FuncC).
You can get from main to FuncA by using CTRL-] on the call to FuncA. Then
you can CTRL-] to get to FuncC. If you now want to go back to main you can
use CTRL-T twice. Then you can CTRL-] to FuncB.

To keep those tags useful when you update your project, you can map a sequence that saves the buffer you are working on and then regenerates the tags automatically. Here is an example:

 vim
 
nnoremap <leader>W :w<CR>:MakeTags<CR>:echo 'ctags have been updated.'<CR>

And on this note, we’re ready to conquer the world.

Dispose of Spam with Disposable Emails And More!

Sébastien Lavoie — Wed, 03 Apr 2019 20:08:00 -0600

Introduction

If your privacy matters to you even just a little, read on, if you dare. There are easy solutions you can apply right now to filter those fools out of your digital life.

Why should I care?

Once your main email address is exposed to attacks because it was leaked in a data breach or your data was somehow sold to a third-party service, it is a hard and time-consuming process to try to unsubscribe to everything or apply filters to automatically delete most of the bad stuff coming in. Many websites won’t respect your privacy and will go ahead and share your email, which can eventually have a snowball effect and you end up getting more emails than there are trees available to print them. As with printing emails, you must agree this is totally irresponsible and should be punished by law .

Because attackers can often retrieve your complete name from your email address (either because you signed up for a service sharing your information from another provider or it’s easy to associate it with you on social media, for example), they can craft advanced phishing emails or create content that’s magically relevant to you thanks to social engineering and if you don’t look close enough, you can fall into their trap.

Then suddenly, because you opened an attachment or went into the dark corners of the Web unbeknownst to you, your laptop fan is spinning all the time at full speed or you get a colorful pop-up telling you that all your files have been encrypted and a ransom, along with only unrecognizable files on your system, convincingly dictates what your destiny looks like. At this point, you are doomed, unless you actually take pleasure in formatting your computer once in a while for the shear joy of it.

So what shall we do about it?

Solution #1: Use a temporary email

This one is quick and easy. You can use a variety of services, including Temp Mail Address, Temp Mail and ThrowAwayMail to name a few. Those are all free services and allow you to get access to a temporary email address and its associated inbox.

Perfect for all those cases when you want to receive a freebie or have access to a specific page that asks for an email and a real name. You simply give a fake but working email address and you’re good to go. Don’t even set it and forget it.

Solution #2: Use a more controlled approach

There is one particular service that I have been using for almost a decade now that eats your spam away on demand. That service is appropriately called Spamgourmet. Does it work? Here are my personal stats:

Your message stats: 805 forwarded, 14,191 eaten. You have 245 spamgourmet address(es).

Does it really work?

Oh yes! From the above stats, you can see that from a total of 14,996 messages being sent to me, I have not received almost 95% of it thanks to Spamgourmet working on auto-pilot all the time… And it’s important to mention that the other 5%, I actually wanted to receive it.

How does it work?

You can create as many email addresses as you require to login to most websites that you do not intend to use regularly and create a label Filtered mail in your inbox or something similar that matches anything sent to *@spamgourmet.com. You can create addresses on the fly without ever needing to log into your Spamgourmet account and set how many emails can be sent to a specific address all at once.

With very few extra steps, you can manage your email addresses on Spamgourmet, remove the ones you don’t want anymore, reset how many emails can be received (increase/decrease that number), etc. You can find out exactly how it works on the main page of Spamgourmet.

Why consider this approach instead of solution #1?

This approach has the advantage that you can know exactly where your spam is coming from and exactly when, as your email may be used quite a long time after your original registration with a service to spam you. If you have created an account on, say, clouds.com with your special email created on the fly without ever needing to go to Spamgourmet, let’s say it’s clouds.my_username@spamgourmet.com, if you receive spammy content sent to that address six months later, don’t look too hard: you know who did it.

Not only you know this, but you can keep on using this made up email for as long as you wish. Need to be in touch with a person who doesn’t fall into any of the categories ['friend', 'acquaintance', 'work', 'intimate', 'trustworthy']? No worries, instantly claim something.my_username@spamgourmet.com and that’s the email you give that person. Since it doesn’t expire and you have full control over how many more emails you can receive at that address at any time, it can simplify a few exchanges where you don’t really want to share your real email, not even to the Nigerian Prince. This way, you can even receive attachments just as normal!

You can even go as far as having trusted senders (from whom you can receive as many emails as you define) and send mail from your custom Spamgourmet emails, including with attachments! For this, you can visit Spamgourmet and generate an email of your choice that will be sending to a specific address email. You will simply send the email to this specially generated address from your email account and voilà! The person on the other end will have a hard time figuring out your real address, except if you added it in your signature.

Solution #3: Using filters

Gmail is one email service that allows you to create filters as you wish: let’s take advantage of that. What you could do is delete only messages that match exactly the groups of terms you never want to read as to not exclude important emails. To create one filter for all of them, you can use the field has words and enter something like the following in the case of GDPR policy updates:

"Privacy Policy Update" OR "GDPR" OR "General Data protection regulation" OR "Updates to our terms of use" OR "Updates to our privacy" OR "updating our privacy" OR "updated our privacy"

If you know more specifically how the words you are looking for appear, you can check for turns of phrases such as Updates to X's Privacy Policy and manage them with the keyword AROUND <number>, where <number> is how many words can be around what you are searching:

"privacy policy" AROUND 3 update

This will look anywhere in the subject or in the content of the email and find the word update as well as updates near the match privacy policy. If you are interested in looking for the word update but not updates, you can specify an exact match with the + sign right in front of it: +update.

_{Note: If you go too broad with the chosen keywords, you may not be able to reply to everything you would like to…}

A next step could be to filter potentially important emails with more keywords but instead of deleting them, you can select a few options for your filter such as Skip the Inbox (Archive it), Mark as read, Apply the label and Never mark it as important. That way, you still have access to all those emails and you can review them separately and quickly at your convenience.

For a list of available search operators, you can refer to this Gmail help page — Search operators you can use with Gmail.

Solution #4: Use the `+` symbol in your email

Gmail lets you add a + symbol in your email address. For example, you can set up your ServiceNameHere email to be username+ServiceNameHere@gmail.com. That way, you know where your spam may be coming from, but it is always more effective to just use a unique address with the above service or even forward emails from another Gmail account so you never have to give away your main email. By doing this, you can then set up filters for individual services. This doesn’t work for all websites as sometimes the + symbol isn’t allowed. In that scenario, there is another way…

Solution #5: Forward secondary emails to your main email

This is pretty straightforward and even though you initially have to do more work to set things up, this can work very well for various reasons:

You get 15GB on each Gmail account. This can be useful, as long as you don’t abuse it and get banned for life without the possibility of ever communicating through email ever again in your lifetime.
You can apply custom filters such as send to trash for each secondary account before forwarding what’s left to your main account. You can then apply a filter in your main account to visually get a hint of where the email is coming from, like a label my.second.email@gmail.com.
You can stop forwarding emails at any moment if you decide. You will have to log into your secondary account and click a few buttons there, but it’s easy, almost painless and you shouldn’t have to repeat the process so often that it gets boring.
You can even set up your main account so that you are able to send messages from your main account as if it were coming from any of your secondary accounts. No more account switching: you get something sent to my.second.email@gmail.com in your main account and you can have it set up so that when you reply to that email, it is automatically sent from that secondary email instead of the main one.

Conclusion

I hope you found something useful in this rambling about spam. I don’t like spam myself, so if you have any tips or tricks you would like to share with me to help in this quest for freedom, please reach out to me at my email shared in plain text at sebastien39571@gmail.com.

Surfing with qutebrowser — a Keyboard-Driven Web Browser

Sébastien Lavoie — Mon, 11 Feb 2019 14:46:00 -0600

What is qutebrowser?

qutebrowser is a web browser that makes great use of Vim commands to navigate. From its website:

qutebrowser is a keyboard-focused browser with a minimal GUI. It’s based on Python and PyQt5 and free software, licensed under the GPL. It was inspired by other browsers/addons like dwb and Vimperator/Pentadactyl.

Why use it?

Perfect companion to any Vim user

The first notable feature of qutebrowser is obviously how well the use of keyboard shortcuts is integrated with the experience of using the software (there is a useful key binding cheatsheet on the homepage). Search bindings (/, n/N, ?), visual mode (v), tabs (gt, T), copy (yy), open URLs (o/O), J and K for switching tabs, etc. Many key bindings will look familiar to Vim users.

It even features a command mode, accessible by typing :, just like with Vim. Settings can be set from there directly, help can be accessed by typing :help [command/setting], the configuration file can be customized on the fly, the position and size of tabs can be set in many ways, history and settings page can be accessed and navigated through like any other page (hjkl, Ctrl + d, Ctrl + u, gg, G), etc.

Even though it is based on Python which is a “slow” language, most of the libraries and the web engine rely on C++ and the end result is a fast and powerful browser that’s totally customizable… Not unlike Vim.

Minimal interface ⇒ more space

Until I upgrade my laptop to a larger screen (≥ 17 inches), my current setup with its 15 diagonal inches benefits tremendously from configuring all applications to use pixels as efficiently as possible — which is why I now use exclusively [i3 as a window manager](/posts/2019/01/08/using-i3-as-a-window-manager-for-increased-pr oductivity/).

qutebrowser doesn’t even have a menu bar. By default, it only displays a small tab bar at the top (which can be moved to another side or removed) and a thin status bar at the bottom to see the URL, the current position in the page expressed in percentage, the number assigned to the current tab, etc. There is also a fullscreen mode available like in most other web browsers with the key F11, which will remove any window decoration and leave you in a (possibly) productive mode.

History, bookmarks and quickmarks

The history page (:history), while being minimal like all the rest, loads extremely fast and is a joy to navigate. The bookmarks page (Sb) is equally simple yet useful. The way I like to open a bookmark is in a new tab by typing gB (go bookmark as a mnemonic. Note that usually all uppercase letters open or do some action in a new space, such as a window or a tab).

Where qutebrowser shines in my opinion is with quickmarks. This is a simple but genius way to find what you are looking for: you type b (or B for new tab) to open a list of pages that are defined with a keyword, you type that keyword (or can type anything to search for a page), move around with arrow keys if necessary to select a page, type Enter and there you go. As far as I know, Google Chrome doesn’t offer the equivalent (only keywords for search engines). Firefox allows to add keywords for any bookmark that you have, but there is no good way to search around for keywords, define them quickly, remove them quickly, etc. qutebrowser comes with a set of commands that serve just this purpose (:quickmark-add, quickmark-del, etc.), apart from adding them very quickly by typing m for quickmarks and M for bookmarks.

Hinting system

You may have tried extensions for other web browsers such as Vimium, Vimperator, or Vimium-FF that let you navigate with Vim shortcuts. They usually use the letter f for following links. Some text appear on the screen for each visible link and you type the letters that match the link you want to see. The best way to get how it works is just to try it out, really.

Well, qutebrowser takes those features and make them even greater! There is, for example, a rapid hinting mode you can access by typing f followed by Ctrl + r and it will open links in the background for as long as you type any matching hint provided as a letter or combination of two letters when there are many visible links on the page. This is especially useful when doing some research to avoid breaking the rhythm on the current reading while preparing more resources to be available.

What’s the best place to start learning about it?

The help page on the website contains all the information you really need. I did stumble upon the following resources, which I would recommend to read in order of appearance:

Quickstart Guide.
[Key bindings cheatsheet](https://raw.githubusercontent.com/qutebrowser/qutebrowser/ma ster/doc/img/cheatsheet-big.png).
FAQ, which is interesting but not indispensable. It did help me take a step forward in trying out qutebrowser though.
Open inside qutebrowser: default keybindings.
Open inside qutebrowser: settings page.
List of commands.

Conclusion

qutebrowser has been around for a while and is very stable. It is ideal for any Vim user and is a great option for anyone interested in efficiency and/or in trying out alternatives. Because I am very fond of relying on the keyboard as much as possible and because I love to program in Python, I have grown to like this web browser very quickly. This is clearly a tool designed for a specific type of user in mind and who knows, you might be one of those.

Using Embedded Terminals Inside Neovim

Sébastien Lavoie — Wed, 16 Jan 2019 17:32:00 -0600

Terminals & Neovim

Terminal buffers are a built-in feature of Neovim. This means that terminals can be launched inside Neovim just like any other buffer, may it be a split window, a new tab or an independent buffer. Why is this so useful? Be prepared to be amazed.

(click to open)

Seamless integration with Vim commands

For a start, terminals are not just opened inside Neovim: they are truly integrated. When you type the letter i in a terminal buffer, it switches to a new mode, Terminal, where you have access to all underlying features of a regular Bash terminal, such as CTRL + r to search, tab completion of commands, CTRL + w to delete a word backwards or CTRL + u to delete the whole line backwards.

When you escape the Terminal mode, you switch back to Normal mode, where all Vim commands are available as usual, such as navigation, search, etc. Where this gets interesting is when you consider that the terminal is just like any other buffer (except it’s not modifiable) and so you can for instance copy its content or paste into it from different registers. You can split them, view the line number, get automatic scrolling when output appears in Insert mode, you can switch back to Normal mode at any time even if a command hasn’t completed… and of course all commands like gt to go to another tab work as always.

Terminals get supercharged with the power of Vim

This is getting exciting (at least for me). Now, having a terminal with more power is useful in many cases:

A whole terminal session can be saved to another file easily by copying the desired range (:%y to copy everything, for example).
Instead of having to scroll with the mouse, all Vim commands are available to search and navigate through the buffer: gg to go to the beginning of the session, G to go to the end, 12G to go to line number 12, / or ? to search forward and backward respectively. You can even set local or global marks to jump back and forth to precise lines consistently!
It’s even possible to send commands directly to a specific terminal or set up a REPL to execute any code, either a selection, a line or a range of lines. I don’t personally use that feature yet, but I see how useful that can be and you can too if you watch this [screencast presented by Drew Neil](https://thoughtbot.com/upcase/videos/neovim-sending-commands-to-a- terminal-buffer) on thoughtbot.com.
If the terminal is opened in Normal mode, the cursor and the current position are kept intact even though new output could appear, such as would be the case if you are running a server in the background or waiting for a system update to finish. This is especially nice for instance if you are trying to debug a web application: you can leave the cursor exactly where you would like to keep reading the output and never get lost… Plus you have the ability to easily move around, search and copy like a ninja!

The workflow is more compact and centralized

Because the terminals are running with one Neovim instance, you get everything in the same place, which is usually how you need to access your work anyway. If for some reasons you need to have multiple instances of Neovim running, this is possible too and in that situation you could simply split them into different workspaces.

Because everything is launched with Neovim, every terminal left open will also be exited when you close Neovim, shutting down any server or quitting any background interaction going on in the terminals. I have found that this behaviour is what I expect pretty much all the time because the idea of having a terminal inside a working session of Neovim is to work on something related, so it makes sense to close everything that’s to do with a single project or task when you exit the text editor. No need for CTRL + d or exit anymore!

Terminal settings to consider

I don’t use many settings or mappings related to terminals, but I guess the nicest one is to remap the Escape key because by default, this is a weird mapping that leads to twisted fingers (<C-\><C-n>). Here is what I currently have in my init.vim file (the equivalent of .vimrc for Neovim):

 vim
 
 
 
set termguicolors " Make colors look better in terminal

" Exit from terminal buffer (Neovim) more easily (remaps Esc key in
" terminal)
tnoremap <C-[> <C-\><C-n>

" Open terminal buffer (M stands for the Alt key)
nnoremap <M-t> :te<CR>

" Switch to terminal buffer automatically (when only one terminal is
" open)
nnoremap <M-0> :b term://<CR>

" Move between windows exactly the same way as usual
tnoremap <C-j><C-k> <C-\><C-N>
tnoremap <C-h> <C-\><C-N><C-w>h
tnoremap <C-j> <C-\><C-N><C-w>j
tnoremap <C-k> <C-\><C-N><C-w>k
tnoremap <C-l> <C-\><C-N><C-w>l

Conclusion

This was a quick overview of a feature that I have neglected for some time but recently realized how well it integrates with my workflow. You can find some more information by typing :h terminal. If you already use Neovim, it’s worth giving it a try! Otherwise, it’s worth giving Neovim a try.

Using i3 as a Window Manager for Increased Productivity

Sébastien Lavoie — Tue, 08 Jan 2019 11:12:00 -0600

What is i3?

i3 is a tiling window manager. To get to know i3 better, it’s good to situate what desktop environments are in the first place.

What are desktop environments?

If you are familiar with Linux, you certainly know about desktop environments such as GNOME, KDE, Xfce… and actually many more are available (you can see this article on Wikipedia for an extended selection)! The classic Graphical User Interface (GUI) on Windows XP was known as Luna and is now called Modern on Windows 10. Aqua is the name of the GUI on macOS. Well, every desktop environment comes with a window manager, the main component that makes interactions with windows possible, like moving, resizing, minimizing or closing them.

Desktop environments are very useful in many ways:

They are usually very easy to set up as they come fully functional out of the box. Like opening a user session on macOS or Windows.
They are sometimes quite customizable, but you don’t have to change anything to get them to work, as they normally set default applications to open with certain file types.
They automatically integrate services such as WiFi network detection, automatic mounting of drives when you plug them in, etc.
You can enable virtual desktops to split your work across different spaces. This concept can grow to [Activities](https://docs.kde.org/trunk5/en/kde-workspace/plasma-deskto p/activities-interface.html), which is a feature implemented in KDE that allows you to use virtual spaces literally for different activities by having settings that are specific to each activity (like launching one application or keeping widgets in determined positions), plus the ability to use multiple virtual desktops inside each activity.
They integrate with applications that are specifically designed to take advantage of the desktop environment in question by adapting colors and themes perfectly to match the general look of the system and arranging settings in a common location for all applications.

Why use a window manager like i3?

Even though desktop environments are user-friendly and include many goodies, they do have several disadvantages that make window managers great alternatives.

Less bloated

Desktop environments are often bloated with many applications that you may not need but that are nevertheless occupying system resources as they have many dependencies. For example, if you use Thunderbird for managing your emails and your desktop environment is GNOME, try to remove Evolution, the default application for emails that comes with it… It’s still relatively easy to disable its processes, but you sometimes have to configure files manually to satisfy your need for removing clutter.

Lower memory and CPU consumption

Other than coming with a set of default applications (more disk space), the whole environment occupies a lot more memory to run smoothly. On my modest laptop, I was still experiencing speed issues because the system was occupying too much RAM when opening heavy applications (lots of tabs when web browsing, photo editing, loading IDEs like PyCharm for programming, etc.) and I had 4 GB of RAM installed at the time. KDE requires at least 600 MB, same is true for GNOME in most recent versions (but used to be over 1 GB not very long ago, just like for KDE). Windows, for example, requires more than 1.5 GB of RAM to operate with basic features. i3 needs less than ~15 MB with as many windows and spaces open as you would ever want. Since there are much less processes to take care of, CPU consumption is also lower, which is more noticeable on older machines.

Keyboard efficiency

There are obviously ways to go about using keyboard shortcuts for pretty much anything you want with desktop environments. However, window managers and especially i3 make this a must, as there is really no reason to use a mouse for moving windows.

First of all, windows are “stuck” in place and never overlap by default. You can’t move them around with a mouse unless they are “floating” windows, which means you can separate them to move them around freely like in most desktop environments. The whole point of using a window manager like i3 is to maximize screen space, so every window opens in full screen. Honestly, the only time I ever found the need to use a floating window with i3 is when using the operating system Windows in a virtual environment when connecting through RDP with Google Chrome on Google Cloud Platform (that is, not very often). Other than that, I find it very practical to split the screen with no overlapping windows, even with my small 15 inches screen.

Because windows are managed the way they are in i3, getting split when multiple windows are in the same workspace and never overlapping, it nurtures the good habit of dividing workspaces appropriately to maximize the space that each application occupies, which is done with keyboard shortcuts. With (customizable) shortcuts, you can split windows, move them to other workspaces, change workspaces, open applications automatically in specific workspaces, etc. Using exclusively the keyboard to manage the windows becomes a huge time saver, and even more so when considering the very small footprint required to use the window manager, making for a lightning fast experience.

Extremely fast customization

Once you get past the initial lack of visual appeal and weird way to move around, you can actually customize many aspects of i3, including fonts, mouse bindings, window border decorations, colors, automatic execution of apps when initiating a session, etc.

Why is it so fast to customize? Because the configuration is all contained in one simple text file and you can make a change and reload the window manager on the fly to see your changes being reflected. Setting the number of workspaces is as easy as adding or removing a line (well, as a bare minimum, otherwise it’s useful to also bind certain keyboard shortcuts to move to those newly created workspaces). Setting a wallpaper is one line, setting a screen lock is another one. Quick and efficient.

Easy to switch layouts and focus

I actually enjoy the default layout quite a lot, in which there exists no overlap between windows (they split as needed) and all windows are visible at the same time in each workspace. If you need to make more space for a window, you can either “focus” on the current window, which will make it full screen and cover every pixel of the screen, or you can move particular windows to other workspaces. This last option will automatically resize windows so that they occupy the maximum space available.

Besides the default layout, you can also stack and tab windows, depending on how you like to work (it is well worth having a look at the i3 user’s guide to see the many other features available). Personally, I prefer seeing everything at once and dividing my work into many workspaces. If you are curious, here is how I currently have my workspaces set up:

Programming — Exclusively for programming purposes.
Terminals — For working in the terminal, opening another instance of a terminal text editor, etc.
Web — Just for Internet. Always full screen unless I open some website that requires to open new windows (like banking), which conveniently split the windows. The web browser automatically launches in the background when opening a session in i3.
Multimedia — Editing photos or watching videos.
Music — ncmpcpp (terminal music player) automatically launches in the background when opening a session.
Experiments — I use this workspace when trying to understand some programming concepts with an interactive IPython console or for breaking the system in one way or another because I don’t know what I’m doing.
Fix — After realizing that sometimes experiments need to be cleaned up a bit, I now use this workspace exclusively to run tools in the background, such as BleachBit for cleaning files or glances (similar to the top command) for watching how the system is doing.
Words — I use that workspace for reading e-books or for writing, either in Neovim or LibreOffice depending on the task.
Tools — This workspace is reserved for anything that I might want to have access to once in a while, like a calendar or KeepassXC for accessing a password database.
sg — I mainly use that workspace to update this very website, but I also use it for setting up local web servers for making personal projects in Flask and Django or even just a temporary server with python -m http.server to share files with other devices on the local network.

Only workspaces that contain windows will appear on the screen at any given time and are automatically created when you access and use them.

What does it look like in action?

Here is a screenshot* of the workspace where this article is being written (click to open):

* _{In this particular scenario, the splits on the right side are
intentionally very small as I do not need to read the output, but need
quick access to a terminal to enter commands. Moving back and forth
between windows is a breeze, so that’s how I currently handle the
situation.}

Note: With Neovim, there is an embedded terminal, which makes things very easy to handle by avoiding splits altogether. In that case, it is also possible to divide a workflow with tabs inside Neovim instead of physically splitting windows.

Alternatively, instead of splitting windows, a more convenient solution on smaller screens might be to use stacking windows with the shortcut $mod + s in each workspace or, to provide that behavior by default, the following can be added to i3’s configuration file (defaults in ~/.config/i3/config):

 bash
 
# Set default container layout
workspace_layout stacking

Conclusion

I am not trying to convince myself anymore: I really prefer this workflow! If you are looking for a change and would like to maximize both your productivity and your system resources, i3 is a great window manager to consider. It doesn’t seem very intuitive at first, but I swear it quickly becomes easy to use and you also end up learning more about how Linux works and set things up manually (just once!) to your likings. For example, I use Rofi instead of dmenu to have a window pop-up to select applications or switch to any window on any workspace… which was only one line to modify in the configuration file.

I have found the following screencasts on YouTube to be quite useful in learning how to configure i3 (apart from the official documentation which is very comprehensive):

Aliases: Also Known as Terminal User's Best Friends

Sébastien Lavoie — Sat, 08 Dec 2018 13:52:00 -0600

Some aliases that I find useful

In all the following examples, the dollar sign $ at the beginning of commands represents the prompt, it should not be typed.

General-purpose

List all aliases

bash

$ alias

Prints all of your aliases. If you have plenty of those, you might prefer to pipe this command with less to get a nice pager that allows you to easily nagivate them:

 bash
 
$ alias | less

Setting an alias in `~/.bash_aliases`

 bash
 
alias c='clear'

This would set c as a shortcut to clear. In order to use the newly created alias, you would have to close the terminal or type the following command in the terminal:

bash

$ source ~/.bash_aliases

Clear the screen

 bash
 
alias c='clear'

I like being absorbed into the emptiness of the terminal, so this one comes in handy to tidy up the work space.

Reset the terminal

 bash
 
alias re='tput reset'

If for some reasons the terminal displays badly or display funky characters, it can usually be reset this way.

Exit from the terminal

 bash
 
alias q='exit'

For exiting the terminal as if you were still in Vim!

Display all file extensions recursively from the current directory

 bash
 
alias allextensions="find . -type f -name '*.*' | sed 's|.*\.||' | sort -u"

It comes in handy to spot if a file shouldn’t be there or to check for lower or uppercase extensions.

Find text inside files, including filenames

 bash
 
alias findinfiles='ag --nobreak --nonumbers --noheading . | fzf'

In this example, the alias is set up with ag, a fast code-searching tool and fzf, a great fuzzy finder.

Reboot and shutdown the system

 bash
 
alias reboot='systemctl reboot'
alias shutdown='systemctl poweroff'

This will reboot or power off the system without needing root privileges in most working conditions.

List and sort files and directories by modification time

 bash
 
alias treeold='tree -hDF | less'

This requires the command tree to be installed. The parameters are (descriptions taken from man tree):

-h: Print the size of files in a human readable way.

-D: Print the date of the last modification time.

-F: Append a ‘/’ for directories, a ‘=’ for socket files, a ‘\*’ for executable files, a ‘>’ for doors (Solaris) and a ‘|’ for FIFO’s, as per ls -F.

Open files quickly with default applications

 bash
 
alias o='xdg-open'

This will open files and URLs specified as argument in the default application detected.

Moving around

If you are going to be working on projects for some time and require to cd into them, I have found the following to be useful:

 bash
 
 
 
$ cdnameOfProject # instead of having to do cd /path/to/project/
$ # More examples:
$ cdcodeabbey # For codeabbey.com
$ cdhackerrank # For hackerrank.com
$ cdeuler # For projecteuler.net
$ cdgit # For all Github repositories

This is not advanced by any means, but it helps quite regularly! Since you can take advantage of tab completion, you can type cd (without adding a space) and then press TAB key to autocomplete the aliases.

 bash
 
alias ...='cd ../..'

Make it easier to navigate into deep directory structures by basically doing cd .. && cd .. to go back up two directories at once.

Listing files

 bash
 
 
 
alias l='ls -CFh'
alias la='ls -Ah'
alias ll='ls -ahlF'
alias ls='ls --color=auto'

Different ways to set up the command ls to quickly see the needed files. The parameters are (descriptions taken from man ls):

-A: Do not list implied . and ...

-C: List entries by columns.

-F: Append indicator (one of \*/=>@|) to entries.

-a: Do not ignore entries starting with .

-h: With -l and/or -s, print human readable sizes (e.g., 1K 234M 2G).

-l: Use a long listing format.

 bash
 
alias aNameOfProject='source /path/to/project/bin/activate'
alias aa='source ~/Programming/anaconda3/bin/activate' # Example using Anaconda distribution

The purpose is to activate a specific virtual environment quickly. The command cd could be added to go to the related project also:

 bash
 
alias gNameOfProject='cd /path/to/project/ && ./.venv/bin/activate'

Where .venv would be the name of the virtual environment.

I like to activate environments starting aliases with a and go and activate at the same time starting aliases with g. This way, it feels like I am speaking the Vim language (cw for change word, for example).

 bash
 
alias da='deactivate'

This will deactivate a virtual environment.

 bash
 
alias p36='python3.6'
alias p='python3.7' # Simply using `p` for main version of Python

Practical way to quickly open the desired Python version.

 bash
 
alias pyclean='find . -regex ".*\(__pycache__\|\.py[co]\)" -delete'

This will delete recursively all files and directories that match one of the following patterns in their name: __pycache__, .pyc or .pyo.

Conclusion

I hope you will find at least one alias to improve your productivity. Of course, you are welcome to chime in with your own suggestions!

Using Vimwiki for Note-Taking

Sébastien Lavoie — Mon, 03 Dec 2018 13:26:00 -0600

What is Vimwiki?

From the official website:

Vimwiki is a personal wiki for Vim – interlinked, plain text files written in a markup language.

As this relies upon Vim’s power to write content in a simple format, this quickly became a viable option to organize more and more notes!

What were the other options considered?

I have used various approaches in the past for different purposes and reasons, including Evernote, Simplenote, Microsoft OneNote, Google Docs, Boostnote, Freeplane/FreeMind (mind-mapping), Workflowy and even plain .txt files. Each has its pros and cons, but I then decided to limit my options based on the following self-imposed requirements:

It has to be available on Linux. Right from the start, this would disqualify many applications such as Notational Velocity, Bear, Quiver, Paper, Ulysses and Squid.
It has to be open source as this is a philosophy that I strongly embrace. Plus, having the ability to freely modify it and contribute to the project is an important additional bonus. Adiós Evernote, Google Docs, Dropbox Paper, Microsoft OneNote, Workflowy and Quip.
It has to be fast to use and it has to make it possible to express oneself in more than one way. Say goodbye to Freeplane (otherwise great for general brainstorming!) and FreeMind (which has been abandoned by its own developers): both are relatively slow on an old machine because they use Java and it is quite a stretch to use them for something other than mind maps. In that same category would disappear draw.io, which is fantastic for making flowcharts and diagrams!
It has to be versatile enough to handle features such as including images, links and attached files and have a way to perform search and replace. Ciao Simplenote which is, well, simple. Even though it doesn’t fit the bill in this case, it remains a great option as it can synchronize your notes with many different devices (iOS, macOS, Android, Windows and Linux). It has a feature that allows you to move a slider which acts as a timeline and shows you a different version of your note since its creation with the actual date and time down to the minute for each restore point. You can also use tags and Markdown and it has options to share and collaborate with others. Highly recommended!
It should have a hefty user base to back it up. This would exclude text editor plugins such as atom-notes for Atom or VSNotes for VS Code, which also lack features for accomplishing all of the above.
On top of everything else, it has to be available offline, in a portable and readable format. Now, after discarding most options, we are left with Boostnote which uses CoffeeScript-Object-Notation and Vimwiki which has its own Wiki syntax that’s similar in many ways to Markdown*. Those are the strongest contenders that I could think of but of course, if you would like to share your recommendations, please do so in the comments below!

* _{I somehow discredited
Emacs simply because I started
to learn Vim first and since I’m still far from understanding all of
its features, I had to postpone the discovery of Emacs.}

One feature-rich alternative to Vimwiki

After settling down on Vimwiki, I later found out about Joplin, which comes with many great features and characteristics such as:

Free & Open Source
Manages notes and todo lists
Search across all notes/todos
Import/Export from/to various formats, including Markdown and even imports from Evernote
Support for attachments
Tags
Synchronization with multiple providers such as Dropbox, Nextcloud, OneDrive and even your own private cloud
Available for Windows, Linux, macOS, Android and iOS
Web Clipper integration

This application left me a great first impression to say the least and I will make sure to stay up to date on its active development, which you can follow on GitHub.

Why did Vimwiki win in the end?

In short

The modal nature of Vim makes it very hard to enjoy any other text editor once you get used to it. The learning curve is quite considerable and nearly infinite, but this is also why I think it is worth investing more time to master it as it has proven to be an everlasting piece of trusty software.

There is a feature in Boostnote to set the Editor Keymap to vim so that you can edit text in a very similar way, but then you miss out on Vim’s Command mode which adds tremendous extensibility and the ability to create any mappings you wish on the fly.

Expanded edition

Boostnote comes with nice features such as Tags, the ability to set multiple storage locations for notes, a Preferences panel to adjust many options, a feature to add code snippets, real-time preview of Markdown being edited, etc. Make no mistake: this is a great program. But there are many Vim features that are hard or impossible to replicate and everything that you can do in Boostnote can be done in Vim also (ctags, emmet syntax, plugins for Markdown, etc.).

For starters, the terminal integration is obviously unmatched. In Vim, CTRL+Z will stop Vim and gives you access to the terminal to do whatever you want to do. From that point, you can simply switch back to Vim by issuing the command fg. The terminal integration goes even further: you can have full access to the terminal inside Vim buffers since Vim 8.1 and that is a feature that has been available in Neovim for even longer.
Even though vim mode can be enabled to edit text, you have to use the mouse to get many tasks done and the editing window can loose the focus. On the other hand, Vim is just one single window by default that you can split however you want, including adding tabs if your heart tells you to.
You have to open your notes with Boostnote if you want them to be fully readable out of the box. Vimwiki does almost no processing with the content of the files so that it is very easy to open them with any other text editor. On a related note, it is much easier to export many notes at the same time with Vimwiki. Boostnote does have a few options to export individual notes (.md, .txt, .html and print), but it is not as user-friendly with many notes.
Vimwiki makes it easy to link notes together and navigate between them, even within subfolders: highlight text, press Enter to create a link and open a new note, write your note and press Backspace to go back to where you created the link. That’s quick and easy!

Conclusion

In the end, it is a matter of taste as those programs are indeed very distinct. Boostnote has a polished interface, is much easier to use and has many settings easily changed. Vim/Neovim, on the contrary, requires a lot of initial effort both to understand and to set up according to your needs, but it does deliver a good dose of productivity… Eventually!

An honorable mention goes to Simplenote, which is a joy to use with mobile devices and allows for quick synchronization between different devices across all the supported platforms.

Where things really get in favor of Vim, you could mention the extensive help system (command :help), the use of macros, words and lines completion, the dot (.) command, the many registers at your disposal for different tasks, the impressive amount of plugins available, the ways in which you can configure mappings, functions… But that’s for a whole new story!

sglavoie.com – Tag: Productivity

From a plan to unattended agent runs: how I drive coding agents one session at a time

Introduction

Why plans, not prompts

The pipeline, step by step

Splitting: where to cut

Expanding: the plan is a set of claims

Preflight: the gate

Completion contracts: who decides what “done” means

What a run looks like

Fresh context, durable handoffs

Pausing is a feature

The controls I use all the time

A second agent, reviewing cold

Guardrails, briefly

When this is overkill

Lessons from four months of building it

Conclusion

Resources and references

External links

From this website

Git the gist of it: common commands for a working workflow

Introduction

Global and local .gitignore

Meaningful commit messages with .gitmessage

My usual Git workflow

Starting a new project

Committing to an existing project

Being committed

rebase

Sample workflow

merge

Sample workflow (kinda)

Managing branches

Aliases

Custom Git sub-commands

Some lesser-known yet incredibly useful commands

git bisect

git rerere

A word on the configuration file

Conclusion

More resources and references

Websites

YouTube

Online courses

References for this article

Using dmenu to Optimize Common Tasks

Introduction

Any Simple Example?

How do You Install It?

Debian-based (such as Ubuntu)

Arch-based (such as Manjaro)

Useful Real-World Examples

Cheat sheets

University shortcuts

File manager shortcuts

Setting Up a Custom Command

Configuration for i3 (bind a keyboard shortcut)

Configuration for cheatsheets.conf

Pipe 1

Pipe 2

Pipe 3

Running a Custom Script

Chaining dmenu prompts

Customize the Look of dmenu

Conclusion

Black: A Python Formatter to Brighten Your Workflow

What is Black?

How to use it?

Use it from the terminal

Use it with Vim

Any example?

Conclusion

fzf - A Fuzzy Finder to Accomplish Anything

Introduction

What is fzf?

Terminal aliases

Vim/Neovim integration

Working with Neovim

Conclusion

Global and local `.gitignore`

Meaningful commit messages with `.gitmessage`

`rebase`

`merge`

`git bisect`

`git rerere`

Solution #4: Use the `+` symbol in your email

Setting an alias in `~/.bash_aliases`