sglavoie.com – Category: Workflow

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

Systematic reviews

Sébastien Lavoie — Sun, 14 May 2023 15:58:00 -0600

Introduction

I used to think that merely using better or more sophisticated tools would magically make me more productive, blaming external factors and technology on my own lack of ability to achieve my dreams. But I’ve come to realize that it was only an escape into the procrastination playground to avoid facing hard work. Working on a system is not the same as working in a system. The former is a form of procrastination, while the latter is the actual work that needs to be done.

While there are great approaches including Zettelkasten and the Getting Things Done methodology, I have found that I work optimally with simpler systems that are easier to maintain, which reduce cognitive load and friction (less to think about and no complicated setup when inputting information either). I used to be an avid user of Todoist where I would implement GTD almost as a pure devotee, making the most of all its (relatively) advanced features, but that was a double-edged sword as dealing with timezone and synchronization issues was more than enough to derail me from the path, sometimes with dire repercussions when tasks would suddenly disappear or be scheduled at the wrong time.

Needless to say, I have since moved on to a simpler system that is more robust and that I can trust. I am not technologically turning back, but I have found Todoist’s weekly review process to be quite effective and easy to follow, so I have decided to adopt it as a basis for my own system, which I will be describing briefly in this post.

A whirlwind tour of the system

What follows is nothing revolutionary, but the simplicity of it just stuck with me. From prior research on the topic as I was building a todo application, it really stood out to me that the most effective systems were the simplest ones, especially when the different components can be neatly decoupled from each other while working well together as a whole. Arguably, the Apple ecosystem has done a great job at this – although I’m still enthusiastic about creating a single software destination to manage one’s life even more efficiently ;).

In reality, I just stuck with the default offerings for maximum compatibility and ease of use, but the truth is that the existing applications I have been in touch with do not fully address all my needs. As I’m not willing to try to bend reality to my will, I have decided to bend my will to reality for the time being and work with what I have. But I digress.

PlantUML source of this diagram

So the main idea here is very simple: twice a day, a daily review occurs and once a week, a more thorough weekly review is performed. Then, at the end of every month and every year, an even more thorough exploration happens both to reflect on the past and plan for the future.

Daily review

PlantUML source of this diagram

The purpose behind the daily review is twofold:

To make sure that the day is planned out and that the most important tasks are completed.
To do a mindful check on one’s wellbeing and re-adjust as needed.

Point 1. is self-explanatory. It serves as a good reminder that task estimation skills are not perfect and that one should not be too hard on oneself if things do not go as planned. Point 2. is a bit more subtle, but it is important to frequently take a step back and reflect on one’s current state of mind and body. That may include taking a break, going for a walk, or even taking a nap. The point is to be mindful of one’s current state and to take action to improve it if needed. In that department, I like to exercise early in the morning, both to expose my eyes to sunlight and to get my blood flowing (more on this in the excellent Huberman Lab podcast!). Besides sleeping well and eating healthy, I have found that this is the best way to ensure that I am in a good state of mind to tackle the day’s challenges.

Make relevant context accessible

One thing I like to do to stay on top of priorities is to “pin” a couple of active notes I’m using from Apple Notes directly inside the list of widgets shown when swiping left with two fingers on the touch pad (or clicking on the clock in the top-right corner). There, I quickly see notes like Working notes (to accompany the projects I’m currently working on), Standup so I can share updates with my team, @next_action which contains a list of stuff I plan to work on next without having to clutter my todo app and another one such as Ideas which I use as a scratchpad to empty my mind of any thoughts that might be distracting me from the task at hand or that might be useful later on.

Another major component of the way I organize tasks (currently with Apple Reminders) is to rely on smart lists and split them by areas of responsibilities. So while I may create tasks under specific lists, I tend to simply schedule everything that’s either recurring or that will need attention in the near future, storing the remaining ideas and potential tasks in Apple Notes.

So in this case, everything being scheduled for today or that has been flagged manually will appear in the Today list. Anything else that has a deadline in the near future will appear in the Scheduled list. Then, I simply divide my set of work in progress (WIP) tasks into work and personal and will drag and drop tasks from other lists/projects as needed to re-prioritize them. To avoid having a large list of items in the WIP lists, I use two separate lists to keep track of the Next actions: these are tasks that do not require immediate attention but used to be scheduled as being more urgent, since priorities will often need to shift under a set of constantly new circumstances.

These tasks will be dragged out of other lists as needed – either from the backlog of tasks or from the WIP tasks to declutter other lists. They will be prioritized as the Next actions to ensure that once the WIP is done, there is a continuity to the system. Just as with other lists, order matters, so that the most important tasks are at the top and the least important ones are at the bottom. This is a simple way to ensure that the most important tasks are always visible and that the least important ones are not forgotten.

Weekly review

The weekly review is a bit more involved, but it is still quite simple. The main idea is to take a step back and reflect on the past week, while planning for the next one. This is where I like to take a look at my calendar and make sure that I have not forgotten anything important. Given the current set of tools I use, I don’t really implement timeboxing as I find that I just tend to miss stuff I put into the calendar if it’s not an “all-day” event. Brace yourself, here it goes.

PlantUML source of this diagram

This probably looks more intimidating than it really is. I usually go through the whole process in under an hour. That may sound like a lot, but it really helps to declutter my mind while giving me the assurance I did my best to plan for the upcoming week. I also like to do this on Sunday mornings, so that I can start the week with clear focus. All in all, I find that this is a great investment and it becomes especially true if I adhere to doing it in the mornings right after I have a delicious cup of freshly ground coffee (but at least 90 to 120 minutes after waking up: again, see Huberman to get fantastic explanations on why this is ideal).

Automatic reviews

Once more, nothing too fancy is happening here, but having smart lists makes it very easy to review what is coming up. In this case, it’s mostly empty as it excludes all the work in progress, which makes it more useful as well since these are already accessible from their own lists, so the review section really highlights anything that is salient and non-recurring.

Monthly and yearly reviews

I can see the benefit in asking more questions and taking more time to plan ahead up to a point, but life is totally unpredictable and I find that it is not worth spending too much time planning for the future. Ultimately, everything is ephemeral: interests, hobbies or even relationships come and go. So my current approach is simply to repeat the weekly process with an emphasis on the things I might have neglected a bit more, such as planning new projects, dissolving old ones that no longer require attention and making sure that I am still on track with my goals at a higher level.

These moments also form a great opportunity to look at finances and make sure that I am not spending too much money on things that do not bring me joy or that I do not need. They also serve as a reminder to take a step back and reflect on the bigger picture, taking a break to look at all the progress that has been made so far. This becomes easier when things are tracked down by writing, and so I maintain a private GitHub repository called life-trail in which I write down a summary of my weekly reviews, keep track of the most important lessons I have learned and main events that happened in my life. This is heavily inspired from having gone through the Self Authoring Program, which I highly recommend to anyone interested in bringing more meaning into their life.

While (I think) I’d love to know for sure where I spend every minute of the day, I tend to track my time with Toggl only when I’m at the computer or reading books on my pretty old Nook e-ink reader. It doesn’t paint the full picture, yet it is not cumbersome to use and provides the kinds of insights I am looking for while forcing me to be more mindful about the actions I take moment to moment.

Conclusion

I have tried many different methodologies to get more organized and, after getting no further than where I used to be, I have reached the following conclusion, which can be elegantly summed up with Nike’s tagline: Just Do It. While one might have lofty goals, it all means nothing if one does not take action towards attaining them. This is why I have decided to adopt a more systematic approach in all aspects of life. This is not to say that I will not be using any tools, but rather that I will be using them with a focus on pragmatism and manifesting actual results.

More resources and references

Huberman Lab podcast - Andrew Huberman.
ProductiviDo - GitHub.
Self Authoring Program - Jordan Peterson.
Solving the Procrastination Puzzle: A Concise Guide to Strategies for Change - Timothy A. Pychyl.
The Weekly Review - Todoist.
Timeboxing - MindTools.
Toggl - Toggl Time tracking.
Work Notes by Sam Matla - Sam Matla.

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.

Managing multiple tmux sessions at once

Sébastien Lavoie — Sun, 19 Sep 2021 18:13:00 -0500

Introduction

Released back in 2007, tmux keeps being amazing! Because I have never bothered automating anything to make its use simpler, it took some time for it to become a working environment I enjoy for everyday use. This is a thing of the past: thanks to Oleksandr Kocherhin from Monsterlessons Academy, who shared his tmux workflow in his YouTube video titled Best Terminal Application for Web Development, I saw a few automation opportunities I thought were worth tackling.

In this post, I’m sharing a little tip about managing tmux sessions that was inspired from the mentioned video. I am using i3wm on Linux, but you can adapt this with any desktop environment as long as you can trigger the execution of programs with a keyboard shortcut in one way or another. I will be using Rofi and the find command, which you can find on Unix systems. If you would rather use dmenu instead of Rofi with this script, this article can serve as a reference. Enough said, let’s get to it.

What is this all about?

The idea is simple: have a few keyboard shortcuts to manage tmux sessions. That means being able to open new sessions and being able to kill them too. I kept this setup very simple on purpose but of course some improvements could be made. For instance, it could be nice to know which projects have already been opened so that the script doesn’t prompt you with a list of projects that include projects that you have already launched, but I haven’t found the need so far to deal with this potential issue as I tend to only work on a couple of projects during the course of a given day.

In summary, here is what we want to achieve in this post:

Configure projects so that when we want to open them, they will be set up in the right directory with servers running, etc.;
Open a tmux session with a keyboard shortcut, listing all projects that were configured in the previous step;
Kill any opened tmux session with another keyboard shortcut.

That’s it!

1. Configuring projects to launch tmux sessions

Firstly, we need to create new files to open our projects in the way we want. Basically, we need to create a file, let’s call it .tmux, and put it at the root of the project we’re interested in working with tmux. Then, we need to put some instructions that will be run with the shell (e.g. Bash or Zsh) so that tmux commands will be run automatically for us and let us “attach” to the session once all the necessary actions are performed. That means we need to make that file executable. In the terminal, this would be done as follows, assuming the project’s folder is the current working directory:

bash

chmod +x .tmux

At last, we want to give some orders to tmux so that when we execute that file, it will open our project in a pre-configured state so we’re ready to go. This will need to be customized depending on your needs, but here is a simple example to illustrate what could happen. So, we could put the following inside the .tmux file:

 bash
 
 
 
#!/bin/sh

set -e

if tmux has-session -t=my-project 2> /dev/null; then
 tmux attach -t my-project
 exit
fi

tmux new-session -d -s my-project -n nvim -x $(tput cols) -y $(tput lines)

# Neovim
tmux send-keys -t my-project:nvim "n" Enter

# Servers
tmux new-window -t my-project -n servers
tmux send-keys -t my-project:servers "cd frontend && yarn start" Enter

tmux split-window -t 2 -v -p 50 # split it into two halves
tmux send-keys -t my-project:servers "cd backend && ap && uvicorn main:app --reload" Enter

tmux attach -t my-project:nvim

Here is what is happening:

If our project, named my-project, has a tmux session already running, then we “attach” to it and nothing more is done.
Otherwise, the session is created in “detached” mode so we can run a few commands smoothly and later attach to the created session.
With the -n flag, we name the window to be created (here, the first window is nvim).
Then, we “send” keys to the session, to that newly created nvim window. In this case, we send a single keystroke n, which is just an alias for executing Neovim.
In a new window named servers, we send keys to execute the frontend server.
Then, we split the second window we just created vertically and we run the commands needed to launch the backend server, again making use of Bash aliases for convenience.
Finally, we attach to the session and we open the first window nvim, ready to work.

And just like this, what takes quite a few steps to do manually can be automated in one go when setting up the environment at the beginning of a working bout. Now, it could be convenient to create a generic template for the above script to use when creating new projects, especially if those tend to be short-lived and share some properties (e.g. maybe they all need to launch some kind of server in the background).

2. Script to open projects

Firstly, we need a way to list and open all “known” projects. This is achieved in this example very simply with the find command as well as with the help of rofi. The script in question is as follows:

 bash
 
 
 
#!/bin/bash

# Get the path to the `.tmux` file to execute using `find` and `rofi`
PROJECT=`find $HOME/dev -type d \( -name node_modules -o -name .venv \
 -o -path name \) -prune -false -o -name '.tmux' \
 | rofi -i -dmenu -theme purple -font 'JetBrainsMono 14' \
 -width 90 -show window`

# Get the full directory path to the `.tmux` file, excluding the filename
PROJECT_DIR=`echo $PROJECT | xargs -I {} dirname "{}"`

# If $PROJECT is empty (e.g. pressing Esc at the prompt), don't do anything
if [ ! -z "$PROJECT" ]; then
 kitty --directory "$PROJECT_DIR" -e "$PROJECT"
fi

So, what this does is this:

It finds all the directories where a .tmux file exists, excluding non-useful folders like node_modules. The -prune flag is passed to avoid recursion further inside a directory once a .tmux file is found. The results of find are “piped” into rofi, which displays the results. User selection is then stored in the PROJECT variable.
Once a file is selected, the full path without the filename is extracted and stored in the PROJECT_DIR variable.
Finally, all that is left to do is check if the user selected a project and if so, run it with the desired terminal from the correct directory. This will be different for most terminal emulators: here, an example is shown with the kitty terminal.

3. Script to close projects

Here, we are concerned with the sessions that are now opened and that we might want to close. In a similar fashion as what we did to open projects, we want to kill them with a script that will run Rofi and do the job silently in the background. One such script that will get us there is shown below:

 bash
 
 
 
#!/bin/bash

# Get the name of all running sessions
TMUX_SESSIONS=`tmux ls | cut -f1 -d ":"`

# No listed session, then notify about it
if [ -z "$TMUX_SESSIONS" ]; then
 notify-send "No active tmux session found"
 exit 0
fi

# Show all running sessions with Rofi and store the selection in a variable
SESSION=`echo $TMUX_SESSIONS | rofi -sep ' ' -i -dmenu -theme purple -font 'JetBrainsMono 14' \
 -width 90 -show window`

# Kill the selected session
tmux kill-session -t $SESSION

In this case, the usage is quite straightforward: only running sessions are shown, so it’s just a matter of choosing the one we want to kill or pressing the Escape key to abort the Rofi pop-up.

Example workflow

It’s a matter of setting up keyboard shortcuts to run the scripts to open and kill projects. For instance, one such configuration for the i3 window manager would be as follows:

 bash
 
bindsym $mod+Mod1+p $exec ~/path/to/projects-start.sh
bindsym $mod+Mod1+k $exec ~/path/to/projects-kill.sh

A simple shortcut lets us choose sessions to open.
Next, if we decide to kill a session at some point, we have another shortcut to do that.

Conclusion

Far from being a perfect solution (although it already feels comfortable as a main driver), this workflow initiates what I think can lead to substantial optimizations when it comes to using tmux. There’s room for improvement when a user selects an already opened session: ideally, we would just switch to that session automatically. These details need to be implemented based on the window manager that’s being used, but suffice to say, it can be done! In any case, I hope this may give you a semblance of inspiration to take this idea to the next level. There are tools to help with session persistence, such as tmux-resurrect, but that’s a topic for another time.

More resources and references

Best Terminal Application for Web Development, original inspiration for this workflow. — Monsterlessons Academy, YouTube.
The tmux wiki, GitHub.
tmux-resurrect, GitHub.

Managing dotfiles with a Git bare repository

Sébastien Lavoie — Sun, 30 May 2021 13:13:00 -0500

Introduction

I have been managing my configuration files for the past year using a technique I originally came across in this YouTube video from DistroTube. This uses a Git bare repository instead of the “usual” way, which consists of using a normal Git repository where one would store the actual configuration files and create symbolic links to all those files to the expected path on the system.

Needless to say, symlinks are a pain to manage when potentially hundreds of files need to be tracked in this way. Fortunately, working with a bare repository is much simpler: there’s neither a need to move files around nor store any of them in the dotfiles bare repository either. Let’s dive in to see how this works! I’ll keep the instructions to the point: for more details, please refer to the article The best way to store your dotfiles: A bare Git repository from Atlassian, the source of knowledge behind this post.

1. Set up the system

Open a terminal and brace yourself to type a few commands. This will need to be done only once on any machine you use.

Set the following variable to the name of the directory where you want to store your dotfiles (e.g. .dotfiles, dotfiles, cfg, etc.):

 bash
 
DOTFILES=dotfiles

Then type the following commands:

 bash
 
git init --bare $HOME/$DOTFILES
alias config='/usr/bin/git --git-dir=$HOME/$DOTFILES/ --work-tree=$HOME'
config config --local status.showUntrackedFiles no

Depending on where you store your terminal aliases (e.g. .bashrc, .zshrc, .bash_aliases, etc.), set the following variable according to your needs:

 bash
 
ALIASES=.bash_aliases

Once that is done, type the following command (or open the file containing your aliases with a text editor to manually put the alias wherever you want):

 bash
 
echo "alias config='/usr/bin/git --git-dir=$HOME/$DOTFILES/ --work-tree=$HOME'" >> $HOME/$ALIASES

You can of course change the config alias to something else. I like to simply use c instead.

1.1 Create a repository to host your dotfiles

At this point, you will want to make sure you have created an empty Git repository on a website such as GitHub, GitLab or BitBucket. In the interface of that website, you should find a place that allows you to copy the link to that Git repository, which might look like something like this: git@github.com:username/dotfiles.git.

1.2 Set the remote to track your dotfiles

With your new Git repository created in the previous step, you will now want to add tracking information to be able to connect to the remote Git repository. You can do so as follows:

bash

config remote set-url origin git@github.com:username/dotfiles.git

For more information about this, you can read the article Setting up SSH and Git for Multiple Accounts if you’ll be using an SSH key to connect and more specifically the official documentation on the git remote command.

2. Use the new system

2.1 On your current machine

Tracking changes will now be a breeze! All we have to do is to add files with our new alias (assuming config was chosen) to Git, commit and push to a remote repository to keep everything neatly backed up.

A typical workflow will look like this:

 bash
 
 
 
config status
config add .gitconfig
config commit -m "Add .gitconfig"
config add .zshrc
config commit -m "Add .zshrc"
config push

2.2 On a different machine

Once yet have set up the system once with a remote repository, then the process becomes simpler as you can clone that repository and save a few steps. Here’s what you’d be expected to do to set up the same dotfiles management system on another machine:

 bash
 
 
 
# set to different values as desired
DOTFILES=dotfiles
REMOTE=git@github.com:username/dotfiles.git

alias config='/usr/bin/git --git-dir=$HOME/$DOTFILES/ --work-tree=$HOME'
echo "$DOTFILES" >> $HOME/.gitignore
git clone --bare $REMOTE $HOME/$DOTFILES
config checkout

At this point, you might see an error message if you have existing configuration files on your machine in locations that are already tracked by Git in your dotfiles on the remote repository. If that’s the case, you can move them to a secure place like so:

 bash
 
mkdir -p .config-backup && \
config checkout 2>&1 | egrep "\s+\." | awk {'print $1'} | \
xargs -I{} mv {} .config-backup/{}

Let’s make sure we don’t show all untracked files again:

bash

config config --local status.showUntrackedFiles no

From here, this will be the same workflow as described in the section 2.1 On your current machine.

Conclusion

No more symlinks: this is definitely a nicer approach! You will need to be a bit more familiar with Git if you need to edit your Git history such as with the rebase sub-command or when adding changes selectively such as with the sub-command add -p to add files interactively — which might be the case if you want to commit only part of the changes made to one file — but that’s a great tool to master anyways, and there’s an article to get the ball rolling: Git the gist of it: common commands for a working workflow ;).

More resources and references

Git Bare Repository - A Better Way To Manage Dotfiles — DistroTube, YouTube
The best way to store your dotfiles: A bare Git repository, the source of the idea for this post. — Atlassian

Setting up SSH and Git for Multiple Accounts

Sébastien Lavoie — Sat, 03 Oct 2020 15:25:00 -0500

Introduction

To work effectively with services such as GitHub and GitLab, it is useful to set up a workflow that doesn’t get in the way, especially when multiple accounts are involved. SSH will be set up to avoid entering the username/password combination every time we interact with remote repositories and Git will be set up to work differently for each account while signing the commits potentially with different GPG keys.

In short, we need to do the following:

Set up SSH locally (in ~/.ssh/);
Set up SSH keys remotely (GitLab, GitHub, Bitbucket, etc.);
Set up Git locally (in ~/.gitconfig);
Set up GPG keys remotely (add our keys(s) to GitLab, GitHub, etc.);
Start interacting with remote repositories.

Setting SSH locally

First, let’s make sure we have some SSH keys to work with. The default location is ~/.ssh/id_rsa (you can just press Enter when asked to save to a path):

bash

$ ssh-keygen -t rsa -C "email@personal.com"

The next key should have a different path:

 bash
 
$ ssh-keygen -t rsa -C "email@work.com"
$ Enter file in which to save the key
 (/home/sglavoie/.ssh/id_rsa): /home/sglavoie/.ssh/id_rsa_work

Add the keys to the authentication agent like so:

bash

$ ssh-add /.ssh/id_rsa
$ ssh-add /.ssh/id_rsa_work

See which keys were added:

bash

$ ssh-add -l # list the keys

If you need to delete any keys that were cached prior to that:

bash

$ ssh-add -D

Now, we need a configuration file:

 bash
 
$ touch ~/.ssh/config
$ chmod 600 ~/.ssh/config

Let’s add some content in there, assuming we deal with GitHub and GitLab, both with a personal account and a work account:

 bash
 
 
 
AddKeysToAgent yes
Host github
 HostName github.com
 User git
 IdentityFile ~/.ssh/id_rsa
Host github-work
 HostName github.com
 User git
 IdentityFile ~/.ssh/id_rsa_work
Host gitlab
 HostName gitlab.com
 User git
 IdentityFile ~/.ssh/id_rsa
Host gitlab-work
 HostName gitlab.com
 User git
 IdentityFile ~/.ssh/id_rsa_work

The directive AddKeysToAgent yes is useful to avoid typing ssh-add path_to_key every time SSH is needed.
The Host can have any name we want, it doesn’t need to match the HostName.
The HostName is the address we need to access. This should be the same thing for all accounts using a particular service (here, GitHub or GitLab).
We can set the user to be git by default.
For each Host, we indicate which IdentityFile to use when trying to work with a remote repository.

Automatically load the keys from the Shell

For Zsh, the following can be added near the top of ~/.zshrc when using the ssh-agent plugin:

 bash
 
# Load multiple SSH keys
zstyle :omz:plugins:ssh-agent identities id_rsa id_rsa_work

With Oh-My-Zsh, the ssh-agent plugin should be contained in plugins like so:

 bash
 
plugins=(git ssh-agent fzf gitignore zsh-autosuggestions history-substring-search)

# Somewhere below
source $ZSH/oh-my-zsh.sh

With this setup, the SSH keys will be loaded when opening a terminal after booting up and those will be available for any subsequent terminal sessions until the user session is exited.

Setting SSH keys remotely

The process will be slightly different on each platform on which we want to authenticate, but the gist of it is to paste the content of the public SSH key in the field when asked to do so.

Setting Git locally

The idea is to have a ~/.gitconfig file from which we load the main Git configuration by default (let’s say, our personal account) and then we load another account – overwriting the Git settings of the personal account with the settings defined for that other account – whenever we navigate to a directory that relates to that other account. Let’s see this in action.

Minimal `~/.gitconfig`

 bash
 
 
 
# default configuration settings to load
[include]
 path = ~/.gitconfig-personal

# when working with company-x
# those settings are loaded only when the
# directory matches the pattern defined
[includeIf "gitdir:**/company-x/**/.git"]
 path = ~/.gitconfig-company-x
[gpg]
	program = gpg
[credential]
	helper = store

The [credential] section with the setting helper = store will store your username/password combination when using HTTPS so you don’t have to type it over and over again. You could also set this to helper = cache if you don’t want to permanently store credentials.
The includeIf directive will be triggered whenever you are in a directory containing company-x in this case so that your correct GPG key and Git settings will be used instead of the default settings for your personal account.
In the block [gpg], your system may be using the program gpg2 instead of gpg.

Minimal `~/.gitconfig-personal` and `~/.gitconfig-company-x`

Example for one of those:

 bash
 
 
 
[user]
 email = email@work.com
 name = Sébastien Lavoie
 signingkey = A343702EBE11E0C2
[commit]
 gpgsign = true

If you don’t have a GPG key already, you can generate one with this command:

bash

gpg --gen-key

To list existing GPG keys to determine the signinkey value to use in those files, you can type:

bash

gpg --list-secret-keys --keyid-format LONG

You might get an output similar to the following (this one is showing only one key):

 bash
 
 
 
sec rsa3072/A343702EBE11E0C2 2020-10-03 [SC] [expires: 2022-10-03]
 EF731EFC008D47D176C05910A343702EBE11E0C2
uid [ultimate] Sébastien Lavoie <email@work.com>
ssb rsa3072/718726CCFED43B47 2020-10-03 [E] [expires: 2022-10-03]

The bit you need to retrieve for the signingkey value comes after the type of encryption, here it’s rsa3072 and the bit we want is A343702EBE11E0C2.

If you need to edit a key, there are plenty of options described with man gpg or man gpg2. For instance, to remove the expiration date for the above key:

bash

gpg2 --edit-key EF731EFC008D47D176C05910A343702EBE11E0C2

At the gpg> prompt, type expire and follow the instructions.

To delete a key, you can do so by referring to the email address like this:

bash

gpg --delete-secret-and-public-key email@work.com

Just follow the instructions from there. You may need to repeat the process multiple times if your email address is associated with more than one key.

Setting GPG keys remotely

Just like with the SSH keys, the process differs from one platform to the other.

Interacting with remote repositories

Now that the Git configuration is set up and we have SSH and GPG keys to authenticate ourselves and verify our identity when committing, respectively, we can start interacting with remote repositories. From the example we have been following, the file ~/.gitconfig-personal will be used by default (and by consequence, our personal account).

The SSH part

When first cloning, change the host so that it reflects what you have in ~/.ssh/id_rsa_correct_key_file. For your personal account, no change would be required:

bash

git clone git@github.com:organization/repo.git

For a repository at work requiring the SSH key set up for the work account, you would need to change to the appropriate host like so (we still use the git user for convenience):

bash

git clone git@github-work:organization/repo.git

For a refresher, the following are the hosts we have set in ~/.ssh/config: github, github-work, gitlab, gitlab-work.

The difference will be noticed when pushing/pulling as seen with git remote -v:

 bash
 
$ git remote -v
origin	git@github-work:organization/repo.git (fetch)
origin	git@github-work:organization/repo.git (push)

Whereas the personal account will have the same host as usual, for instance git@github.com:organization/repo.git.

The GPG part

If we want to keep our personal and work Git configurations separate (and we probably want that! ;)), it’s only a matter of ensuring that the includeIf pattern contains, in this example, company-x somewhere in the path. When this is the case, we will see with git config --list in the cloned repository that our personal account details are loaded first, but if the includeIf directive matches, the settings for that other account will be applied on top and used when committing.

If you type git config --list and search for the word “email” in the output, it will appear only once when the default ~/.ssh/id_rsa key is used (or whatever is read for the IdentityFile from the SSH configuration file) while you will see that same personal email showing up first in a work repository, but then later in the output you will find the work email, work GPG key and so on.

Conclusion

This is one possible kind of setup we can use to work with SSH and GPG comfortably. This is pretty much a “set it and forget it” approach as long as you remember the following:

SSH: Change the SSH host when cloning. If the repository is not publicly available, it would fail anyways (or you may realize you can clone it if it’s a public repo but have no push access).
Git: Make sure you are in a directory where the includeIf directive will kick in to set up the email, GPG key and so on.

One nice tip to help with the latter bullet point could be to define an alias, say in ~/.bash_aliases, something like what follows:

 bash
 
cdwork='cd /path/to/work/dir/with/appropriate/pattern'

Then, you simply cdwork and store all your Git repositories for work under that root repository, which would always match the desired pattern by default. That’s it. Anything else related to the personal account can be cloned anywhere on the file system since this is the default configuration file used. For more Git-related content, you might enjoy reading Git the gist of it: common commands for a working workflow.

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.

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):

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!

Tmux Integration with Vim/Neovim — First Steps

Sébastien Lavoie — Mon, 19 Nov 2018 20:31:00 -0600

tmux integration

tmux offers many advantages in the context of remote access to another machine, but it also shines on a local setup! Here is how I currently like to set it up.

Configuration file

 ~/.tmux.conf
 bash
 
 
 
# split panes using | and -
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

# switch panes using Alt-arrow without prefix
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D


# Enable mouse mode (tmux 2.1 and above)
set -g mouse on

source-file "${HOME}/.tmux-themepack/blue.tmuxtheme"

This is all very self-explanatory. Many themes can be found here.

Automating the launch of a default session

This is a small Bash script that I like to have for automatic set up of a development environment with tmux and Vim/Neovim. As my current workflow, I enjoy the following:

 ~/.tmux_default_session.sh
 bash
 
 
 
#!bash
# var for session name (to avoid repeated occurences)
sn=dev

tmux new-session -s "$sn" -d

# Create 3 windows
tmux new-window -t "$sn:0" -n "nvim"
tmux new-window -t "$sn:9" -n "python"
tmux new-window -t "$sn:8" -n "terminal"

# Split terminal window vertically, then split the right pane
# horizontally, then switch to the left pane (identified by `FOCUS IS
# HERE`).
# _________________
# |>_ |>_ |
# | | |
# | FOCUS |-------|
# | IS |>_ |
# | HERE | |
# -----------------
tmux split-window -h
tmux split-window -v
tmux select-pane -L

# Set up Neovim ready to open files
tmux send-keys -t "$sn:0" C-z 'nvim .' Enter

# Set up alias for IPython and clear the screen when entering IPython
tmux send-keys -t "$sn:9" C-z 'ipython' Enter
tmux send-keys -t "$sn:9" 'clear' Enter

# Select window #0 and attach to the session
tmux select-window -t "$sn:0"
tmux -2 attach-session -t "$sn"

Aliases to make use of

I add the following aliases in ~/.bash_aliases to automate a chunk of the workflow:

 ~/.bash_aliases
 bash
 
 
 
# This will launch tmux with the desired configuration
alias dev='bash ~/.tmux_default_session.sh'

# This will kill the tmux server if the need arises. By detaching from
# the tmux session, you simply run this command and can reattach easily
# to the default session configuration on another project.
alias kdev='pkill tmux'

# If the session has been detached but the tmux server is still running,
# I use the following alias to quickly reattach to the default session
# named `dev` in that example.
alias adev='tmux attach-session -t dev'

tmux demo

(click to open image)

The content of this post can be found on GitHub.

sglavoie.com – Category: Workflow

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

Systematic reviews

Introduction

A whirlwind tour of the system

Daily review

Make relevant context accessible

Weekly review

Automatic reviews

Monthly and yearly reviews

Conclusion

More resources and references

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

Managing multiple tmux sessions at once

Introduction

What is this all about?

1. Configuring projects to launch tmux sessions

2. Script to open projects

3. Script to close projects

Example workflow

Conclusion

More resources and references

Managing dotfiles with a Git bare repository

Introduction

1. Set up the system

1.1 Create a repository to host your dotfiles

1.2 Set the remote to track your dotfiles

2. Use the new system

2.1 On your current machine

2.2 On a different machine

Conclusion

More resources and references

Setting up SSH and Git for Multiple Accounts

Introduction

Setting SSH locally

Automatically load the keys from the Shell

Setting SSH keys remotely

Global and local `.gitignore`

Meaningful commit messages with `.gitmessage`

`rebase`

`merge`

`git bisect`

`git rerere`

Minimal `~/.gitconfig`

Minimal `~/.gitconfig-personal` and `~/.gitconfig-company-x`