Perdi — Blog

Habits for Debugging Faster

perdidev@gmail.com (Perdi) — Tue, 15 Sep 2026 00:00:00 GMT

Debugging speed is mostly about habits, not cleverness. These are the ones that have saved me the most time, roughly in the order I use them.

Make it fail on demand

Before changing anything, find a way to trigger the bug reliably. A bug you can reproduce in ten seconds is half fixed. A bug you can only see “sometimes” is a guessing game.

Then shrink it. Remove inputs, steps and features until the smallest case that still fails remains. Along the way you usually discover what the bug does not depend on.

Read the actual error

It sounds obvious, but I still catch myself skimming. Read the message in full, then read the stack trace from the top and find the first frame that is your code. The message often names the exact variable or line, and the trace shows how you got there.

One hypothesis at a time

Guess a cause, decide what you would observe if you were right, and check. Change one thing per experiment. If you change three things and the bug disappears, you have learned nothing about which one mattered.

Writing the hypothesis down helps. If I cannot explain the problem in a couple of sentences, to a colleague or to a rubber duck, I probably do not understand it yet. Often the explanation itself reveals the mistake.

Bisect everything

Binary search is the best debugging tool there is. Use it on history and on data.

For history, git bisect finds the commit that introduced a bug in a handful of steps. If you have a command that exits non-zero on failure, it can run unattended.

git bisect start
git bisect bad HEAD
git bisect good v1.4.0
git bisect run npm test
git bisect reset

Without run, git checks out a middle commit and you mark it with git bisect good or git bisect bad yourself. Bisecting works far better when commits are small and focused, which is one more reason for writing good commit messages and keeping changes tidy.

For data, halve the input. If a 10,000-line file breaks the parser, try the first half, then the half of that, until you reach the offending line.

Log with context

A bare console.log("here") tells you little. Log named values, and wrap them in an object so the names are printed alongside them.

function applyDiscount(cart, coupon) {
  console.log("applyDiscount:input", { cartId: cart.id, total: cart.total, coupon });
  const rate = coupon?.rate ?? 0;
  const result = cart.total * (1 - rate);
  console.log("applyDiscount:output", { rate, result });
  return result;
}

Log at boundaries: what went in, what came out. Remove the logs when you are done.

Use the debugger for state you cannot reason about

When the logic is too tangled to simulate in your head, set a breakpoint and inspect. A debugger lets you see every variable at once, step line by line, and evaluate expressions without editing code. In Node, node --inspect-brk app.js lets Chrome DevTools or your editor attach.

Write the failing test first

Once you understand the bug, capture it in a test before fixing it. Watch the test fail, apply the fix, and watch it pass. That proves the test actually detects the problem, and it keeps the bug from coming back.

 describe("applyDiscount", () => {
   it("applies a percentage coupon", () => {
     expect(applyDiscount({ total: 100 }, { rate: 0.1 })).toBe(90);
   });
+  it("ignores an expired coupon", () => {
+    expect(applyDiscount({ total: 100 }, { rate: 0.1, expired: true })).toBe(100);
+  });
 });

Take a break

If you have been stuck for an hour, walk away. Fresh eyes spot what tired ones skip, and many of my hardest bugs have been solved in the shower or on a short walk.

What to do next

Pick one habit and apply it to your next bug. For me, forcing myself to write down a hypothesis before touching code made the biggest difference. If your bug involves promises, async/await in JavaScript without the confusion covers a few common traps worth checking first.

How to Run Effective Code Reviews

perdidev@gmail.com (Perdi) — Tue, 24 Mar 2026 00:00:00 GMT

What a review is for

I think of code review as a conversation with three goals: catch correctness problems, check that the design fits the codebase, and spread knowledge so that more than one person understands each change.

Style policing is not on that list. Arguments about quotes, import order, or line length are a waste of human attention. Let a formatter and a linter settle them in CI, and keep reviewer energy for things a tool cannot judge.

The author’s side

Most of what makes a review good happens before the reviewer opens the page.

Keep pull requests small

A change that fits on one screen gets read. A 1,500-line change gets skimmed and approved. In my blog starter, small PRs worked well: each one did a single thing, and reviews usually finished the same day.

Explain the change and review it yourself

Link the issue, describe the approach, and say what you are unsure about. A template makes that the default:

## What and why

<!-- One or two sentences. Link the issue: Closes #123 -->

## How to test

<!-- Commands or steps a reviewer can follow -->

## Notes for the reviewer

<!-- Risky areas, trade-offs, things you want a second opinion on -->

Before requesting review, read your own diff as if someone else wrote it. This command gives a quick overview of what the PR touches:

git diff main...HEAD --stat

I regularly find leftover debug lines and unrelated edits this way. Clean commit messages help here too, see Writing Good Commit Messages.

The reviewer’s side

Respond within one working day, even if only to say when you will get to it.
Read the description first, then the tests, then the diff. Tests show intended behavior.
Ask questions instead of giving orders: “What happens if the list is empty?” invites a better answer than “Handle empty lists.”
Praise good decisions. Review is not only a hunt for faults.

Label your comments

Prefixes remove ambiguity about what is required:

blocking: must be fixed before merge.
question: I do not understand yet, and I may be wrong.
nit: a minor preference, take it or leave it.

A suggestion can be as small as a code change in the comment:

- const items = posts.filter((p) => p.data.draft === false);
+ const items = posts.filter((p) => !p.data.draft);

Something like “nit: !p.data.draft also covers a missing field” tells the author this is optional.

What I look for

A short checklist keeps me consistent:

Behavior: does it do what the description says?
Edge cases: empty input, large input, failures, concurrency.
Tests: do they fail without the change?
Naming: will the next reader understand it?
Security: untrusted input, secrets, permissions.
Performance: anything accidentally quadratic in a hot path?
Docs: does a README or comment need an update?

When you disagree

Separate “must fix” from “preference”. If it is a preference, say so and let the author decide. If it is a real disagreement, move to a call or a chat rather than a fifth round of comments, then write the outcome back in the PR so the decision is not lost. When two reasonable designs remain, the author who will maintain the code usually gets the final say.

Measuring review health

I only track one number: time to first review. Long waits cause large PRs, context switching, and resentment. Review size and the number of back-and-forth rounds are useful secondary signals. Treat them as conversation starters for the team, never as individual performance metrics.

Next steps

Add a pull request template to your repository this week, and agree on comment labels with your team. When the next review stalls, check whether the PR is simply too big. Better debugging also makes reviews easier, so debugging habits is a good companion read.

Big-O Notation Without the Anxiety

perdidev@gmail.com (Perdi) — Tue, 13 Jan 2026 00:00:00 GMT

Big-O has a reputation as interview trivia, but the idea is small and useful. You do not need the maths; you need a feel for how code slows down as data grows.

What Big-O answers

Big-O describes how the amount of work grows as the input grows. It does not tell you how many milliseconds something takes. It tells you what happens when n goes from a thousand to a million.

The classes you actually meet

Five cover almost everything in day-to-day web code.

O(1) and O(log n)

Constant time means the work does not depend on input size. Reading an array index is the typical example.

const firstItem = items[0];

Logarithmic time means each step discards half the remaining data. Binary search on a sorted array is the standard case.

function binarySearch(sorted, target) {
  let lo = 0;
  let hi = sorted.length - 1;
  while (lo <= hi) {
    const mid = Math.floor((lo + hi) / 2);
    if (sorted[mid] === target) return mid;
    if (sorted[mid] < target) lo = mid + 1;
    else hi = mid - 1;
  }
  return -1;
}

A million items need only about twenty steps.

O(n), O(n log n) and O(n^2)

Linear time touches each item once. find is O(n) in the worst case, because it may scan the whole array.

const user = users.find((u) => u.id === id);

Good general-purpose sorting is O(n log n), which is what Array.prototype.sort gives you in practice.

const sorted = [...numbers].sort((a, b) => a - b);

Quadratic time usually means a loop inside a loop over the same data.

for (let i = 0; i < items.length; i++) {
  for (let j = i + 1; j < items.length; j++) {
    if (items[i] === items[j]) console.log("duplicate", items[i]);
  }
}

As n grows, the curves diverge dramatically, and the quadratic one is the one that eventually hurts.

Dropping constants and lower terms

If a function does 3n + 10 operations, we call it O(n). Constants and smaller terms stop mattering as n grows, so Big-O keeps only the dominant one. Two sequential loops are still O(n), while a loop nested in a loop is O(n^2).

A practical fix: includes versus Set

This is the most common real-world win I see. Calling includes inside a loop scans an array each time.

// O(n^2): includes scans b for every item in a
function commonSlow(a, b) {
  return a.filter((x) => b.includes(x));
}

// O(n): building the Set is linear, each has() is constant on average
function common(a, b) {
  const lookup = new Set(b);
  return a.filter((x) => lookup.has(x));
}

The trade is a bit of extra memory for a much faster lookup.

For small n, measure

Big-O ignores constants, and for small inputs constants dominate. A simple array scan over 20 items can beat a Set because of lower overhead. Before optimising, measure with realistic data.

const a = Array.from({ length: 20000 }, (_, i) => i);
const b = Array.from({ length: 20000 }, (_, i) => i * 2);

console.time("includes");
commonSlow(a, b);
console.timeEnd("includes");

console.time("set");
common(a, b);
console.timeEnd("set");

performance.now() works too if you want the numbers in code. Measuring instead of guessing is also the heart of habits for debugging faster.

Space complexity in a paragraph

Space complexity asks the same question about memory. commonSlow uses O(1) extra space apart from its result, while common uses O(n) for the Set. Faster code often costs memory, so it is worth knowing which resource is scarcer in your situation.

What to do next

Pick a hot path in your own code, such as a loop that calls includes, indexOf or find, and ask what happens at ten times the data. If the answer is “much worse”, try a Set or Map, then measure before and after.

Shell Aliases and Functions That Save Time

perdidev@gmail.com (Perdi) — Tue, 18 Nov 2025 00:00:00 GMT

If you type the same long command more than a few times a day, the shell can do the typing for you. Aliases and functions are the two tools for this, and picking the right one avoids a lot of confusion. Here is what I have settled on after years of tweaking.

Alias or function?

An alias is plain text substitution at the start of a command line. It is perfect for shortening a command with fixed options. The limitation is that arguments are only appended at the end, so an alias cannot place them in the middle or run several steps with logic.

A function is a small shell script living in your session. It takes positional arguments ($1, $2, "$@"), can use conditionals, and can run multiple commands. My rule: start with an alias, and switch to a function the moment you need an argument anywhere but the end.

Aliases worth having

# git
alias gs='git status -sb'
alias gl='git log --oneline --graph --decorate -20'
alias gd='git diff'

# safer file operations
alias rm='rm -i'
alias cp='cp -i'
alias mv='mv -i'

# navigation and listing
alias ll='ls -lAh'
alias ..='cd ..'

On the rm -i line: it prompts before every deletion, which saves you once and annoys you often. Many people prefer a trash tool such as trash-put from the trash-cli package, which moves files to the desktop trash so they can be restored. Whichever you choose, make it a deliberate habit rather than relying on luck.

Functions for the rest

mkcd() {
  mkdir -p -- "$1" && cd -- "$1"
}

extract() {
  case "$1" in
    *.tar.gz|*.tgz) tar xzf "$1" ;;
    *.tar.bz2)      tar xjf "$1" ;;
    *.tar.xz)       tar xJf "$1" ;;
    *.zip)          unzip "$1" ;;
    *.gz)           gunzip "$1" ;;
    *) echo "extract: unknown format: $1" >&2; return 1 ;;
  esac
}

alias ports='ss -tulpn'

note() {
  local dir="$HOME/notes"
  mkdir -p "$dir"
  echo "$(date +%H:%M) $*" >> "$dir/$(date +%F).md"
}

mkcd creates a directory and enters it, which no alias can do cleanly. extract saves you from remembering tar flags. ports lists listening TCP and UDP sockets with their processes (run it with sudo to see processes you do not own). note appends a timestamped line to a file named after today’s date, so note fix flaky test in CI is a one-second capture. My notes CLI grew out of exactly this function.

Where to put them

Bash reads ~/.bashrc for interactive shells. Many distributions already source ~/.bash_aliases from it, which keeps your additions separate. If yours does not, add one line:

 # ~/.bashrc
 export EDITOR=vim
+[ -f ~/.bash_aliases ] && . ~/.bash_aliases

Then reload with source ~/.bashrc. For zsh, the same code goes in ~/.zshrc (or a sourced file); the aliases and the functions above work unchanged.

Inspecting what you have

alias            # list all aliases
alias gs         # show one
type gs          # gs is aliased to `git status -sb'
type mkcd        # shows the function body
unalias gs       # remove for this session
command rm file  # bypass the alias once (or use \rm)

type is the most useful of these because it tells you whether a name is an alias, a function, a builtin, or a file on disk.

Keeping them tidy and portable

Keep one file under version control, such as a dotfiles repository, and symlink it.
Prefer descriptive function names over two-letter cryptic ones unless you type them constantly.
Avoid shadowing common commands with different behavior; scripts you run interactively may surprise you.
Guard anything non-portable, for example command -v trash-put >/dev/null && alias rm='trash-put'.
Remove what you have not used in months.

If you are still building up your command-line basics, Linux terminal essentials is a good companion.

What to do next

Run history | awk '{print $2}' | sort | uniq -c | sort -rn | head to see your most-used commands, then turn the top three into aliases today. Add a function only when an alias stops being enough.

TypeScript Generics With Real Examples

perdidev@gmail.com (Perdi) — Tue, 07 Oct 2025 00:00:00 GMT

Generics look intimidating in library typings, but in everyday code they solve one simple problem: keeping type information that would otherwise be thrown away. I will build up from small helpers.

The problem: any loses information

Say you write a helper that returns the first item of an array.

function firstAny(items: any[]): any {
  return items[0];
}

const n = firstAny([1, 2, 3]); // any, so n.toFixed() and n.nope() both compile

The caller gets any back, so the compiler stops helping. A type parameter fixes that by linking the input type to the output type.

export function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([1, 2, 3]); // number | undefined
const s = first(["a", "b"]); // string | undefined

T is inferred from the argument. You rarely need to write first<number>(...) yourself.

Constraints with extends

Sometimes the function needs to know something about T. A constraint says “any type, as long as it has this shape”.

export function byId<T extends { id: string }>(
  items: T[],
  id: string,
): T | undefined {
  return items.find((item) => item.id === id);
}

Callers can pass any array of objects with a string id, and they get back their own full type, not just { id: string }.

A typed fetchJson, and its limits

A generic return type is handy for API helpers. In my budgeting app, I use one like this for every endpoint:

interface Transaction {
  id: string;
  amount: number;
  category: string;
}

export async function fetchJson<T>(url: string): Promise<T> {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return (await res.json()) as T;
}

async function load(): Promise<Transaction[]> {
  return fetchJson<Transaction[]>("/api/transactions");
}

Be honest about what this does: as T is a cast. TypeScript trusts you, and nothing is checked at runtime. If the server changes its response, the types will still claim everything is fine. For data crossing a trust boundary, validate it with a schema library such as Zod and infer the type from the schema.

Generic types

Types can take parameters too. A Result type makes failures explicit instead of relying on exceptions.

export type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

export function parseAmount(input: string): Result<number> {
  const n = Number(input);
  return Number.isFinite(n) && input.trim() !== ""
    ? { ok: true, value: n }
    : { ok: false, error: new Error(`Invalid amount: ${input}`) };
}

Checking result.ok narrows the union, so value and error are only available where they exist. The = Error part is a default type parameter: callers can write Result<number> and only spell out the second argument when they need a custom error type.

keyof for safe property access

To read a property by name, constrain the key to the keys of the object.

export function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

// amounts is number[]; pluck(transactions, "amout") is a compile error
const amounts = pluck([{ id: "1", amount: 12 }], "amount");

The return type T[K][] follows the chosen key, so "amount" gives number[].

When not to use generics

If a type parameter appears only once in the signature, it is not relating anything to anything. It is probably unnecessary.

function printLength<T extends { length: number }>(value: T): void {
function printLength(value: { length: number }): void {
  console.log(value.length);
}

Both versions behave the same, but the second is easier to read. Reach for a generic when the output depends on the input, or when two parameters must share a type.

What to do next

Look through your codebase for helpers typed with any or unknown plus a cast, and check whether a type parameter would remove the cast. If you want a refresher on handling the async side of fetchJson, see async/await in JavaScript without the confusion.

systemd Basics: Services, Units, and Timers

perdidev@gmail.com (Perdi) — Tue, 19 Aug 2025 00:00:00 GMT

On most modern Linux distributions, systemd is the first process the kernel starts, PID 1. It brings up the system, supervises services, collects their logs, and schedules recurring jobs. You do not need to master all of it, but a working knowledge pays off the first time you deploy something that must stay running.

Units in one minute

systemd manages resources described by unit files. The type is the file extension:

.service runs a daemon or a one-shot command.
.timer triggers another unit on a schedule.
.socket, .mount, and .target cover sockets, filesystems, and groups of units.

Your own system-wide units belong in /etc/systemd/system/, while packages install theirs under /usr/lib/systemd/system/.

systemctl essentials

systemctl status nginx          # state, recent logs, main PID
sudo systemctl start nginx
sudo systemctl stop nginx
sudo systemctl restart nginx
sudo systemctl enable nginx     # start at boot
sudo systemctl enable --now nginx   # enable and start in one go
sudo systemctl disable nginx
sudo systemctl daemon-reload    # re-read unit files after editing

Remember the difference: start affects now, enable affects boot. After editing any unit file, run daemon-reload or systemd keeps using the old version.

The status output is worth reading closely. It shows whether the unit is active, when it started, its main PID, and the last few log lines, which is often enough to diagnose a failure without opening anything else.

For services that belong to your user rather than the system, add --user. Units go in ~/.config/systemd/user/, and no sudo is needed:

systemctl --user status notes-backup.service

Writing a small service

Say I have a script that backs up my notes directory. It runs, finishes, and exits, so a one-shot service is enough. The [Unit] section describes the service and its ordering, and [Service] says what to execute and as whom:

[Unit]
Description=Back up notes to the archive disk
After=network-online.target

[Service]
Type=oneshot
User=perdi
ExecStart=/usr/local/bin/notes-backup.sh

For a long-running process, you will want it to come back after a crash. Here is the edit:

 [Service]
 ExecStart=/usr/local/bin/notes-server
+Restart=on-failure
+RestartSec=5

on-failure restarts the process only after a non-zero exit or a crash, not when you stop it deliberately, and RestartSec avoids a tight restart loop. Save, run sudo systemctl daemon-reload, then restart the service. Make sure the script is executable; the permissions article on Linux file permissions explains why that matters.

Reading logs with journalctl

systemd captures stdout and stderr from services into the journal, so you rarely need a custom log file or a log rotation setup. Every line is stored with a timestamp and the unit that produced it, which makes filtering simple.

journalctl -u notes-backup.service            # everything for the unit
journalctl -u notes-backup.service -f         # follow live
journalctl -u notes-backup.service --since "1 hour ago"
journalctl -u nginx --since today -p err      # only errors
journalctl -b                                 # current boot

Replacing cron with a timer

A timer is a second unit that activates the service with the same base name. Create it next to the service:

[Unit]
Description=Run notes backup daily

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Persistent=true is the feature I miss most in cron: if the machine was off at the scheduled time, the job runs at the next boot. Enable the timer, not the service:

sudo systemctl daemon-reload
sudo systemctl enable --now notes-backup.timer
systemctl list-timers --all             # next and last run times
systemd-analyze calendar "Mon *-*-* 03:00"   # validate a schedule

Compared with cron, you gain logging through the journal, dependency ordering, and a clear status view. The cost is two files instead of one line. The pairing works by name: notes-backup.timer starts notes-backup.service automatically, so you never enable the service itself.

What to do next

Pick one cron job or nohup command you currently rely on and convert it to a unit. Start with --user units so mistakes stay in your home directory, and check the result with systemctl status and journalctl -u. Once that works, add Restart= and resource limits as needed.

Writing Good Commit Messages

perdidev@gmail.com (Perdi) — Tue, 08 Jul 2025 00:00:00 GMT

Why history is documentation

A commit message is the one piece of documentation that is written at the exact moment a change is made. Six months from now, someone (very often me) will run git blame on a strange line and wonder why it exists. The diff shows what changed. Only the message can say why.

Good messages also make reviews faster and git bisect output readable. I treat the message as part of the change, not as paperwork after it.

Anatomy of a commit message

A message has up to three parts, separated by blank lines:

Subject: imperative mood, around 50 characters, no trailing period.
Body: explains why the change was needed, wrapped at about 72 characters.
Footers: references and credits, one per line.

The subject line

I write it so it completes the sentence “If applied, this commit will …”. “Add retry to the upload client” works. “Added retry” and “Adding retry” do not. A short subject also survives git log --oneline without being truncated.

The body and footers

The body is for context the diff cannot carry: the symptom, the constraint, the alternative you rejected. Skip the line-by-line retelling of the code. Footers such as Fixes #123 let the tracker close the issue, and Co-authored-by gives credit to pair programming partners.

Passing -m twice gives you a subject and a body without opening an editor:

git commit -m "Fix off-by-one in pagination offset" -m "The offset was computed from the page number instead of the
zero-based page index, so the first page skipped ten items.
Use page - 1 and add a regression test.

Fixes #123
Co-authored-by: Ana Silva <ana@example.com>"

Bad messages and better ones

Most weak messages fail the same way: they say nothing a reader could search for.

Before	After
fix stuff	Fix off-by-one in pagination offset
updates	Bump sharp to 0.33 to fix ARM build failures
WIP	Extract token parsing into its own module
address review	Reject empty slugs in the post loader

The “after” versions name the thing that changed and hint at the reason. You can check how your own history reads at any time:

git log --oneline -5

Keep commits atomic

One commit should hold one logical change. If my working tree contains a refactor and a bug fix, I stage them separately with git add -p, which walks through each hunk and asks whether to include it:

git add -p
git commit

Small commits are easier to review and revert. If you cannot summarize a commit without the word “and”, it is probably two commits. This pairs well with the habits in How to Run Effective Code Reviews.

Fixing history before you share it

Typo in the last message, or a forgotten file? Amend it:

git commit --amend

For a mistake in an older commit on my own branch, I create a fixup commit and let Git move it into place:

git commit --fixup a1b2c3d
git rebase -i --autosquash main

Only rewrite commits that nobody else has based work on. Once a branch is shared, add a new commit instead.

A note on Conventional Commits

Prefixes like feat: and fix: make changelogs and version bumps automatable, and they force a small amount of classification. The trade-off is that the prefix eats into your 50 characters, and people often pick a type just to satisfy a linter while the message itself stays vague. I find them worthwhile when tooling consumes them and optional otherwise.

A convention for your team

Agreeing on a few rules matters more than which rules you pick:

Imperative subject, about 50 characters, no period.
A body whenever the reason is not obvious from the diff.
A reference to the issue or ticket in a footer.
Squash fixup commits before merging.

Write this down in your contributing guide, then try it for two weeks. The next time you chase a bug with good debugging habits, notice how often the answer is sitting in git log.

Linux File Permissions: chmod, chown, and umask

perdidev@gmail.com (Perdi) — Tue, 27 May 2025 00:00:00 GMT

Permission errors are one of the first walls newcomers hit on Linux, and “fixing” them with brute force is a habit that causes real security problems. The model is small enough to learn in one sitting, so let’s do that.

Reading ls -l output

ls -l deploy.sh
# -rwxr-xr-- 1 perdi devs 1204 Mar  3 10:12 deploy.sh

The first column is ten characters. The first is the type (- file, d directory, l symlink). The remaining nine are three triplets: owner (user), group, and others. Each triplet shows read (r), write (w), and execute (x), or - when missing. After the link count come the owning user (perdi) and owning group (devs).

The kernel checks in order: if you are the owner, the owner triplet applies; otherwise, if you are in the group, the group triplet applies; otherwise the others triplet does. It never combines them.

Numeric and symbolic chmod

Each permission has a value: read is 4, write is 2, execute is 1. Add them up per triplet and you get an octal digit. For 754, the owner gets rwx (7), the group gets r-x (5), and others get r-- (4).

Both styles do the same job:

chmod 754 deploy.sh          # numeric: set everything at once
chmod u=rwx,g=rx,o=r deploy.sh   # symbolic: same result
chmod +x script.sh           # add execute for everyone
chmod g-w,o-rwx secrets.env  # tweak only what you mean to
chmod -R u+rwX,go-w project/ # capital X: execute only on directories

I prefer symbolic mode for small adjustments because it does not clobber bits I did not mention.

Directories behave differently

On a directory, r lets you list names, w lets you create or delete entries inside, and x lets you traverse it, meaning access items by path. Without x on a directory you cannot cd into it or open files within, even if the files themselves are readable. This is why web server errors often trace back to a parent directory missing x.

Changing ownership

sudo chown perdi file.txt              # change owner
sudo chown perdi:devs file.txt         # owner and group
sudo chown -R www-data:www-data /srv/site
chgrp devs shared/                     # change group only

Only root can change a file’s owner. A regular user can change the group to one they belong to.

What umask does

New files do not start at 777. The shell’s umask removes bits from the defaults: 666 for files, 777 for directories. With the common 022, write is removed for group and others, giving 644 files and 755 directories.

umask          # 0022
umask 077      # private by default: 600 files, 700 directories
touch a && mkdir b && ls -ld a b

Set it in ~/.bashrc if you want a stricter default. A umask of 077 suits a personal machine holding keys and tokens.

setuid, setgid, and the sticky bit

These are special bits shown in a fourth, leading octal digit.

setuid (4): an executable runs as its owner. passwd uses this.
setgid (2): on a directory, new files inherit the directory’s group, which is useful for shared project folders.
sticky (1): in a directory like /tmp, only a file’s owner can delete it.

chmod 2775 shared/    # setgid + rwxrwxr-x
chmod +t /srv/drop    # sticky bit

Be careful with setuid on anything you write yourself.

Common mistakes

Running chmod 777 to make an error disappear. It lets every user modify the file, and it hides the real cause. Find out which user needs access and grant exactly that.
Using chmod -R 755 on a tree, which marks every data file executable.
Making SSH keys group- or world-readable; ssh refuses them. Use chmod 600 ~/.ssh/id_ed25519.
Forgetting that sudo creates root-owned files in your project.

What to do next

Run ls -l in your home directory and explain every column to yourself. Then audit one real project: check what owns your deployment directory and whether any file is more open than it needs to be. If you are still getting comfortable with the shell, start with Linux terminal essentials.

Async/Await in JavaScript Without the Confusion

perdidev@gmail.com (Perdi) — Tue, 22 Apr 2025 00:00:00 GMT

Most async bugs I have run into come from a fuzzy mental model, not from the syntax. Once the model is clear, async/await is pleasantly boring. Here is the version I wish I had been given earlier.

Promises are values for “later”

A promise is an ordinary object that stands in for a result that is not ready yet. It is pending, then it either fulfils with a value or rejects with an error. It never changes state again after that.

const response = fetch("https://example.com/api/users");
console.log(response); // Promise { <pending> }

async/await is syntax on top of promises. An async function always returns a promise, and await unwraps one.

What await really does

await pauses the async function, not the thread. JavaScript keeps running other code while the awaited promise is pending, and resumes your function afterwards.

async function loadUser(id) {
  console.log("start");
  const res = await fetch(`https://example.com/api/users/${id}`);
  console.log("got response");
  return res.json();
}

loadUser(1);
console.log("runs second");

The output order is start, runs second, got response. The code after loadUser(1) does not wait for it.

Error handling

A rejected promise turns into a thrown exception at the await, so try/catch/finally works as you would expect.

async function save(form) {
  setLoading(true);
  try {
    const res = await fetch("/api/save", { method: "POST", body: form });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
  } catch (err) {
    showError(err);
  } finally {
    setLoading(false);
  }
}

Note the res.ok check. fetch only rejects on network failures, so a 404 or 500 arrives as a normal response.

Sequential versus parallel

The classic mistake is awaiting independent work one item at a time. Each call waits for the previous one, so total time is the sum instead of the maximum.

-const user = await getUser(id);
-const orders = await getOrders(id);
-const prefs = await getPrefs(id);
+const [user, orders, prefs] = await Promise.all([
+  getUser(id),
+  getOrders(id),
+  getPrefs(id),
+]);

The same applies to loops. await inside a for...of is right when each step depends on the last. For independent items, start everything first:

const users = await Promise.all(ids.map((id) => getUser(id)));

Partial failure with allSettled

Promise.all rejects as soon as one promise rejects. When you want every result, successful or not, use Promise.allSettled.

const results = await Promise.allSettled(ids.map((id) => getUser(id)));
const users = results
  .filter((r) => r.status === "fulfilled")
  .map((r) => r.value);
const failures = results.filter((r) => r.status === "rejected").length;

Floating promises

Forgetting await is easy and quiet. The function runs, but nothing waits for it and nothing catches its errors.

save(form); // floating: a rejection becomes an unhandled rejection
await save(form); // fine

In Node, an unhandled rejection crashes the process by default. In TypeScript projects I enable the @typescript-eslint/no-floating-promises lint rule so the mistake gets flagged in the editor.

Timeouts with AbortSignal

fetch has no timeout by default. AbortSignal.timeout() gives you one without any manual timer cleanup.

try {
  const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
  console.log(await res.json());
} catch (err) {
  if (err.name === "TimeoutError") {
    console.error("Request took longer than 5 seconds");
  } else {
    throw err;
  }
}

A typed example

In TypeScript, an async function returns Promise<T>, and await gives you the T.

interface User {
  id: string;
  name: string;
}

export async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`https://example.com/api/users/${id}`, {
    signal: AbortSignal.timeout(5000),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return (await res.json()) as User;
}

That as User is only a cast, not a check. I cover how to make this safer in TypeScript generics with real examples.

What to do next

Search your codebase for await inside loops and ask whether the iterations are really dependent. Then add a timeout to every network call. When something still behaves strangely, my notes on habits for debugging faster cover how to narrow it down.

Linux Terminal Essentials Every Developer Needs

perdidev@gmail.com (Perdi) — Wed, 12 Mar 2025 00:00:00 GMT

You can do a lot of development work without ever leaving the terminal, but only if a small core of commands is second nature. This is the set I reach for daily. None of it is exotic, and all of it works in a stock bash installation, so you can rely on it on a fresh server, in a container, or on a colleague’s laptop.

Navigating the filesystem

Start with knowing where you are and what is around you.

pwd          # print the current directory
ls -la       # long listing, including hidden files
cd -         # jump back to the previous directory
cd           # with no argument, go home

cd - is the one people tend to miss. It toggles between two directories, which is handy when you are bouncing between a source tree and a log folder.

When you need more than two places, use a directory stack:

pushd ~/projects/api    # go there, remember where you were
pushd /var/log          # stack another one
dirs -v                 # show the stack with indexes
popd                    # return to the previous entry

Finding things

find locates files by name, type, size, or age. grep searches inside them.

find . -name "*.ts" -not -path "./node_modules/*"
find . -type f -mtime -1          # files changed in the last day
grep -rn "TODO" src/              # recursive, with line numbers
grep -rni --include="*.md" "systemd" .

If you search code often, install ripgrep (rg). It respects .gitignore, skips binary files, and is much faster on large repositories. The equivalent of the first grep above is simply rg -n TODO src/.

Pipes and redirection

Every program has standard output (1) and standard error (2). Pipes and redirects let you connect them.

ps aux | grep node | wc -l        # chain commands with |
ls -la > listing.txt              # overwrite a file
echo "done" >> build.log          # append to a file
make > build.log 2>&1             # send both streams to one file
make 2>&1 | tee build.log         # watch the output and save it

The order in 2>&1 matters: it means “send stderr to wherever stdout points right now”, so it must come after the > redirect. tee is the right tool when you want to see output live and keep a copy.

Viewing files

Avoid dumping large files with cat. Use a pager or look at the edges.

less +F app.log      # follow mode; Ctrl-C to stop following, q to quit
head -n 20 data.csv  # first 20 lines
tail -n 50 app.log   # last 50 lines
tail -f app.log      # stream new lines as they arrive

Inside less, /pattern searches forward, n jumps to the next match, and G goes to the end.

Job control

A long-running command does not have to block your shell.

Ctrl-C stops the foreground process.
Ctrl-Z suspends it and returns your prompt.
bg resumes the suspended job in the background.
fg brings it back to the foreground.
jobs lists what the current shell is managing.

npm run build         # takes a while... press Ctrl-Z
bg                    # let it continue in the background
jobs                  # [1]+ Running  npm run build &
fg %1                 # bring job 1 back

For work that must survive closing the terminal, look at tmux or a proper service; I cover the latter in systemd basics.

Searching your history

Press Ctrl-R and start typing. Bash searches backwards through history for a matching command; press Ctrl-R again to cycle to older matches, Enter to run, or the right arrow to edit first. Combined with history | grep docker, you rarely need to retype anything long.

Habits worth building

Tab-complete everything. It prevents typos and teaches you what exists.
Use man and --help before searching the web; tldr pages are a nice shortcut for examples.
Quote paths and patterns that contain spaces or wildcards.
Preview destructive commands first, for example run the find command on its own before adding -delete.
Turn repeated command lines into aliases once they annoy you. I wrote about that in shell aliases and functions.

What to do next

Pick two items from this list that you do not use yet, such as cd - and Ctrl-R, and force yourself to use them for a week. Once they are automatic, add the next pair. Small, deliberate repetition beats reading another cheat sheet.