DEV Community: Javi Palacios

Git LFS: managing large files without breaking your repository

Javi Palacios — Wed, 23 Sep 2026 15:50:35 +0000

Someone on the team added assets to the repository. Figma exports, a design system PSD, the demo video linked from the README, a database snapshot "just for testing" that nobody deleted because nobody was sure if it was still needed. They added it the same way they'd add any file: git add, git commit, git push. Git accepted everything without complaint. Git doesn't have opinions about this kind of thing.

You find out it's a problem when you try to clone the repo on a new machine. Four minutes in, you're at 23%.

git count-objects -vH

count: 3124
size: 412.50 KiB
in-pack: 8932
packs: 2
size-pack: 4.73 GiB
prune-packable: 0
garbage: 0
size-garbage: 0 bytes

4.73 GB. For a web app. No videos, according to a quick scan of the current branch. Except eight months ago someone did add a 600 MB database snapshot and then deleted it in the next commit — from the working tree. In Git, deleting a file from the tree doesn't remove it from history. The object stays in the packfile, riding along with every clone, indefinitely.

Why Git and binary files don't get along

Git handles text files remarkably well. When you modify a source file, Git doesn't store the whole thing again — it stores a delta: exactly what changed between the previous version and the new one. A 50 KB file with twenty modified lines produces a delta measured in bytes. History stays lean. Clones are fast.

Binary files break that model entirely. A 200 MB PSD is, from Git's perspective, an opaque sequence of bytes with no recognizable structure. There's no useful delta to compute. So Git stores the full file every time it changes.

200 MB × 50 design revisions = 10 GB that every developer downloads when they clone, forever, regardless of whether the project still exists, the designer moved on, or the file was "deleted" three versions ago.

This isn't a Git bug. It's a mismatch: Git was designed for source code, and large binaries simply don't fit the model it was built around.

What Git LFS does

Git LFS (Large File Storage) is an official Git extension that solves the problem with a clean idea: instead of storing the binary in the repository, it stores a pointer — a 130-byte text file that says "the real file is on this LFS server, it has this hash, and it weighs this much."

Your Git repository only versions that pointer. The binary lives on a separate storage server — GitHub LFS, GitLab LFS, or one you run yourself. When you need the actual file, Git LFS downloads it automatically on checkout.

A pointer file looks like this:

version https://git-lfs.github.com/spec/v1
oid sha256:4d7a2f8c1e9b3d6a5c0e7f2a8b4d9c1e3f5a7b2d4c6e8f0a1b3c5d7e9f1a2b3c
size 209715200

That three-line text file represents your 200 MB Photoshop project. It's a bit absurd. It also works.

Your repository stays lightweight because Git history only contains pointers. The heavy files are downloaded on demand — only when you check out a commit that references them.

Installation

Git LFS is a separate binary you install alongside Git:

# macOS and Linux (Homebrew)
brew install git-lfs

# Ubuntu / Debian
apt install git-lfs

# Arch Linux
pacman -S git-lfs

After installing, activate it once for your user account:

git lfs install

Updated Git hooks.
Git LFS initialized.

This sets up the Git hooks LFS needs to intercept push and pull operations. Skip this step and git lfs track will appear to work but accomplish nothing — silently, with no error, which is the worst kind of not working.

Telling LFS what to track

Inside your repository, specify which file types LFS should manage:

git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "*.zip"

⚠️ The quotes are not optional. Without them, your shell expands the glob before LFS sees it, and LFS ends up registering only the specific files that exist in the current directory right now — not a general pattern. Every new asset you add later goes through regular Git, untracked by LFS, and you're back where you started.

These commands write to .gitattributes:

*.psd filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text

.gitattributes is committed to the repository — unlike the hooks living in .git/hooks/ that we covered in the previous Git hooks tutorial. When someone clones the repo, LFS reads that file to know exactly what it's responsible for. Add it:

git add .gitattributes
git commit -m "chore: configure Git LFS tracking"

The daily workflow

Here's the good part: once LFS is configured, nothing changes in how you work.

# Add a large file exactly as you normally would
git add assets/demo-video.mp4

# Commit it
git commit -m "feat: add product demo video"

# On push, LFS sends the binary to the LFS server
# and the pointer goes into your Git repository
git push origin main

LFS is entirely transparent. No special commands for your regular workflow. What actually happens on push is different — the binary goes to the LFS server, the pointer goes to Git — but from your side, it looks the same.

To see which files are currently managed by LFS:

git lfs ls-files

8f3c2a1 * assets/demo-video.mp4
4d7a219 * design/logo-v3.psd
a1b2c3d * exports/database-snapshot.zip

Cloning repositories that use LFS

When you clone a repo that uses LFS, tracked files download automatically:

git clone https://github.com/your-org/your-repo.git

If you want to clone without downloading the binaries — a CI pipeline that only needs the code, for example:

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/your-org/your-repo.git

Pointers land in the working tree, but the actual files don't. Fetch specific ones when you need them:

git lfs pull --include="assets/demo-video.mp4"

For CI pipelines running dozens of times per day, skipping LFS downloads where they're not needed isn't a minor optimization — it's the difference between a bandwidth quota that lasts the month and one that runs out before the second week.

The limits nobody mentions until you hit them

This is where Git LFS stops feeling like a free solution and starts feeling like a product decision.

GitHub Free includes 10 GB of storage and 10 GB of bandwidth per month. That bandwidth limit is not for what you upload — it's for what gets downloaded. Every clone, every CI checkout, every deploy that pulls your assets counts against your quota.

10 GB sounds reasonable. Then you have eight developers cloning the repo regularly, a pipeline running forty times a day, and a designer pushing updated assets every other week. Turns out it goes faster than you'd expect.

When you exceed the quota, GitHub disables LFS support until the next billing cycle. Not a warning, not a slowdown — disabled. Clones start failing in confusing ways because pointers can no longer be resolved, and anyone troubleshooting the problem without knowing LFS is involved is going to have a rough afternoon.

Options when the free quota isn't enough:

GitHub data pack: 50 GB of storage + 50 GB of bandwidth for $5/month.
Self-hosted LFS server: more control, more setup and maintenance work.
Reconsider the architecture: do those files actually need to be in Git?

Alternatives depending on what you're storing

Git LFS isn't the only option, and for some use cases it's not the right one.

For machine learning datasets: DVC

If you're working with trained models, datasets, or ML experiments, DVC is built specifically for that use case. It works on top of Git, versions data alongside code, and supports S3, GCS, and Azure as storage backends. The integration with ML tooling is considerably better than anything you'd get from LFS.

For static assets that don't need versioning

If the asset doesn't need a version history — a marketing banner, a demo video that gets fully replaced rather than revised, a static PDF — an S3 bucket or a CDN is cheaper and simpler than LFS. The repository references the URL; the file lives outside of Git entirely.

For the advanced case: Git Annex

Git Annex allows distributing large files with per-repository granularity — you can have clones that only download the files they actually need, not everything. The configuration curve is steeper than LFS; for most teams, LFS is sufficient.

Key concepts from this lesson

Git stores binary files as full objects because it can't compute useful deltas on them — history grows linearly with every revision.
Git LFS stores a 130-byte pointer in your repository; the actual file goes to a separate server.
git lfs install runs once per user account, not once per repository.
git lfs track "*.psd" always needs quotes so it registers a pattern, not just current files.
.gitattributes is committed to the repository — unlike hooks in .git/hooks/.
The normal workflow (add, commit, push) doesn't change after setup.
GitHub Free includes 10 GB of storage and 10 GB of bandwidth per month; exceeding either disables LFS.
In high-frequency CI/CD pipelines, use GIT_LFS_SKIP_SMUDGE=1 where you don't need the binaries.

Git LFS isn't a perfect solution — the bandwidth limits surface faster than expected, and it doesn't help with large files already buried in your history (that requires rewriting the past, which is its own category of adventure). But it's the right answer to the most common version of the problem: someone committed large binary files, the repository quietly ballooned, and now every clone is a patience exercise.

That wraps up Module 8 — Advanced Git Features. Next, we start Module 9 — Productivity and Tooling, where we'll look at how to make Git work faster for you with configuration, aliases, and tools built around real-world workflows.

Never stop coding!

Git Worktrees: multiple working directories from a single repository

Javi Palacios — Tue, 22 Sep 2026 14:26:20 +0000

Somewhere on your machine there's a folder called my-project-2. Or my-project-backup. Or, if you've been at this long enough, my-project-FINAL-no-really-this-one. You don't bring it up in standups. It doesn't live inside the repo, so it's not in .gitignore either. It just exists, quietly, at some undisclosed path in your filesystem, doing the job your first manual clone was supposed to handle.

Or you do the stash dance: git stash, switch branch, do the thing, git stash pop, untangle whatever the pop left behind — and there's always something — then get back to where you were, slightly less sure of exactly where that was. Every time. It works. Like leaving one screw out of an IKEA shelf works: the thing is standing, but you're not entirely confident it should be.

git worktree isn't some obscure command for people who read Git documentation for fun. It's the official answer Git had prepared while everyone was making manual clones and calling it a workflow.

What a worktree is and why it exists

A clone? A symlink? A renamed copy of the repository? None of those.

A worktree is a working directory linked to an existing Git repository. Each worktree has its own active branch, its own working tree and staging area — but they share the same history, the same objects, the same refs. Technical version: multiple working environments connected to the same underlying .git. Tuesday morning version: you can have my-project-hotfix/ and my-project-feature/ open in your editor at the same time, each on its own branch, and when you commit in one, the other knows.

Think of it as multiple workbenches. One has the feature in progress. One has the urgent hotfix. One has the teammate's branch you need to review. None of them interfere with the others. When you're done with one, you close it and it's gone.

my-project/             ← main directory, branch feature/login
├── .git/               ← the real .git folder lives here
└── src/

my-project-hotfix/      ← worktree, branch hotfix/critical-bug
├── .git                ← file, not folder
└── src/

my-project-review/      ← worktree, branch fix/auth-issue
├── .git                ← file, not folder
└── src/

Secondary worktrees have a .git file — not a folder, a plain text file pointing to the main repository. Git handles all the internal plumbing. You don't need to open it, understand it, or think about it; just know that it's what separates a worktree from a clone. All three directories share the disk space for Git history. The only rule: two worktrees can't be on the same branch at the same time.

Creating your first worktree

The basic command:

git worktree add ../my-project-review fix/auth-issue

This creates ../my-project-review and checks out fix/auth-issue there. If the branch doesn't exist yet, create it in the same step:

git worktree add -b feature/new-feature ../my-project-feature main

-b feature/new-feature creates the branch from main. The directory exists, the branch exists, you can work — without touching anything in your current directory.

Listing all active worktrees

git worktree list

/home/fjpalacios/projects/my-project          9f3c2a1 [feature/login]
/home/fjpalacios/projects/my-project-hotfix   3b7d9e2 [hotfix/critical-bug]
/home/fjpalacios/projects/my-project-review   8c1f4d3 [fix/auth-issue]

Path, current commit, active branch. Git keeps a record of all worktrees in the repository and shows them here. If you try to check out a branch that's already active in another worktree, Git stops you — not because it's forbidden, but because having the same branch in two places is just confusing.

Removing a worktree

When you're done:

git worktree remove ../my-project-review

This removes the directory and cleans up the internal reference. If there are uncommitted changes, Git refuses:

error: '../my-project-review' contains modified or untracked files, use --force to override

To force it:

git worktree remove --force ../my-project-review

--force tells Git: "I know what I'm doing, delete without asking." Git always believes you — that's the issue. Use it when you're certain nothing will be lost. Not pretty sure. Not I think so. Certain.

Real use cases

Reviewing a PR without leaving your work

You're on feature/dashboard, hours in with no commits. A PR comes in for review. Without worktrees: stash, switch, review, come back, pop, untangle. With worktrees:

git worktree add ../review-pr-234 origin/feature/pr-to-review
cd ../review-pr-234
# Review the code, run the tests, leave comments
cd ../my-project
# Everything is exactly where you left it

Urgent production hotfix

You're on feature/complex-refactor, two hours in without committing. Production reports a critical bug:

# Create the worktree directly from main
git worktree add -b hotfix/critical-login ../hotfix-urgent main

# Fix, test, commit, and push from there
cd ../hotfix-urgent
# ...fix, commit, push...
git push origin hotfix/critical-login

# Your feature branch hasn't moved
cd ../my-project

No stash, no branch switch, no lost context. The main directory stays on feature/complex-refactor exactly where you left it.

Comparing branches side by side

You want to see the differences between main and feature/new-branch directly in your editor:

git worktree add ../my-project-main main

Open both directories in parallel — two terminal panes, or if you're on Neovim, diff them directly with vimdiff:

vimdiff ../my-project/src/auth.ts ../my-project-main/src/auth.ts

For those who prefer a mouse and don't mind the Electron startup tax, code --diff does the same.

Cleaning up orphaned worktrees

Sometimes a worktree ends up in ghost state: you deleted the directory by hand, or removed the branch before the worktree. Git doesn't clean up what it doesn't understand — it keeps the reference registered indefinitely, and throws this error the next time you try to create something with the same name:

fatal: '/home/fjpalacios/projects/my-project-old' already exists

To see all worktrees in detail, including the problematic ones:

git worktree list --porcelain

To clean up references to worktrees no longer on disk:

git worktree prune

When not to use worktrees

Worktrees don't replace stash, they don't replace branches, and they're not the tool for every context switch:

If you switch branches constantly in the same directory: worktrees work best when each one has a clear mission and a relatively long life. For fast, frequent context switches, stash is still more direct.
If the repository has large files: each worktree needs its own working tree. History is shared, but directory contents aren't — if the repo is heavy, multiply accordingly.
If you only need to look at another branch without working on it: git show branch:path/to/file or git diff main..feature is enough. You don't need a full directory for that.

Worktrees make explicit something that was already happening — chaotically — through manual clones and the stash dance: sometimes you need to be in more than one place at once. my-project-2 can finally retire. Git had the infrastructure for this all along; it was just waiting for you to use it.

Next tutorial: Git LFS — how to manage large files (binaries, assets, datasets) that shouldn't live in your normal Git history.

Never stop coding!

Docker image optimization: from 1.2 GB to 85 MB

Javi Palacios — Mon, 21 Sep 2026 14:47:50 +0000

At some point you run docker images and see a number that doesn't look right. A Node.js API with three endpoints and a database connection: 1.2 GB. A Go binary that compiled to 8 MB, sitting inside an 823 MB image. A Python script that reads a CSV and returns JSON: 980 MB.

The container works. It deploys fine. And it's carrying a compiler, a package manager, three versions of libssl, and an entire Debian system that hasn't executed a single instruction since it booted.

This is the last lesson in the images module, and it's where we close the loop: take everything from multi-stage builds, BuildKit, and security practices and produce images that contain exactly what they need and nothing more.

The base image pyramid

The choice of base image is the single highest-leverage decision in image optimization. The size differences aren't marginal:

Base	Approximate size
`node:20`	~1.1 GB
`ubuntu:22.04`	~77 MB
`debian:12-slim`	~74 MB
`node:20-alpine`	~135 MB
`alpine:3.19`	~7 MB
`scratch`	0 MB

node:20 is built on debian:12. node:20-alpine is built on alpine:3.19. The difference isn't which version of Node they ship — both ship Node 20. The difference is how much operating system comes with it.

Alpine uses musl libc instead of glibc, busybox instead of bash and coreutils, and apk instead of apt. For most applications this makes no difference. For some it does — native dependencies that expect glibc will fail in ways that aren't immediately obvious. Worth testing before assuming compatibility.

Switching from node:20 to node:20-alpine is the highest-ROI optimization in this entire lesson. One line change. 88% smaller image.

scratch: the extreme case

FROM scratch is exactly what it sounds like: an empty filesystem. No OS, no shell, nothing. It only works for fully static binaries, which in Go is the default with CGO_ENABLED=0:

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o app .

FROM scratch
COPY --from=builder /app/app /app
ENTRYPOINT ["/app"]

The first time you see the result — 8 MB where there used to be 800 — it feels like finding a cheat code. The second time you try it on a different application, it doesn't start because there are no SSL certificates for outbound HTTPS, and you realize scratch means it. No certificates, no timezone data, nothing you didn't explicitly copy.

Both reactions are completely expected. For runtimes like Node.js, Python, or Java, scratch isn't the answer. That's where distroless comes in.

Distroless images

Google maintains a set of images designed for exactly this scenario: they contain only what's needed to run your application — the runtime, SSL certificates, timezone data — without a shell, without a package manager, without anything you'd use to poke around inside a container.

If someone asks "what's the most secure minimal base for a production container?", distroless is the answer without needing to think about it. No shell means no shell exploitation. No package manager means no package manager exploitation. Minimal attack surface as a design principle, not as an afterthought.

For Go (or any static binary):

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o app .

FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/app /app
ENTRYPOINT ["/app"]

static-debian12 ships SSL certificates and timezone data. It weighs around 2 MB. The benefits of scratch without having to remember what you forgot to include.

For Node.js:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --production

FROM gcr.io/distroless/nodejs22-debian12
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["dist/index.js"]

Available distroless images for the most common runtimes:

Runtime	Image
Static binary	`gcr.io/distroless/static-debian12`
glibc	`gcr.io/distroless/base-debian12`
Node.js 22	`gcr.io/distroless/nodejs22-debian12`
Python 3	`gcr.io/distroless/python3-debian12`
Java 21	`gcr.io/distroless/java21-debian12`

One honest limitation: no shell means no docker exec -it <container> sh. If you're used to jumping inside containers to inspect things, distroless changes that workflow. The :debug variant adds busybox and enables exec — use it for development environments where you need to debug, not for production.

Analyzing your image with dive

Before optimizing anything, you need to know what's taking up space. docker history gives you layer sizes:

docker history my-app:latest

IMAGE         CREATED BY                                      SIZE
a1b2c3d4e5f6  CMD ["node", "dist/index.js"]                  0B
...           COPY --from=builder /app/dist ./dist            2.3MB
...           COPY --from=builder /app/node_modules ./node_m  198MB
...           RUN npm ci --only=production                    0B

Useful, but it doesn't tell you what's inside each layer. For that, there's dive.

Installation

# macOS and Linux (Homebrew)
brew install dive

# Ubuntu / Debian — dive isn't in the official repos; easiest path is running it via Docker:
docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock wagoodman/dive:latest <image>

# Arch Linux
pacman -S dive

Basic usage

dive my-app:latest

Opens an interactive terminal UI where you can navigate through each layer and see exactly which files were added, modified, or deleted.

There's a specific moment everyone has in their first dive session: you find the layer taking up 60% of the image size, expand it, and recognize it. It's your dev dependencies. Not the base image's — yours. The ones that ended up there because COPY --from=builder /app/node_modules copied everything without filtering, and the build stage installed everything including typescript, jest, all the @types/* packages, and whatever else your development workflow needs.

Total Image size: 487 MB
Potential wasted space: 0 B
Image efficiency score: 87%

Layer 3: COPY --from=builder /app/node_modules ./node_modules  [312 MB]
  └── node_modules/
       ├── typescript/          [28 MB]  ← not needed at runtime
       ├── @types/              [15 MB]  ← definitely not
       ├── jest/                [12 MB]  ← also no
       └── ...

# CI mode: returns pass/fail based on image efficiency
CI=true dive my-app:latest

In CI pipelines, this flag evaluates whether files are deleted in later layers (a sign that cleanup could have happened earlier) and returns a non-zero exit code if the image doesn't pass the efficiency threshold. Useful for preventing poorly optimized images from reaching production.

Layer optimization

Choosing the right base gets you most of the way there. The rest comes from how you write RUN instructions.

Clean up in the same layer

Each RUN instruction creates a new layer. If you add files in one RUN and delete them in the next, the files are still in the image — they're marked as deleted in the new layer, but the original layer with the files is still there:

# ❌ The apt files are still in the image — the previous layer keeps them
RUN apt update && apt install -y curl
RUN rm -rf /var/lib/apt/lists/*

# ✅ Cleanup happens in the same layer, no trace left
RUN apt update && apt install -y curl \
    && rm -rf /var/lib/apt/lists/*

The same principle applies to anything that downloads temporary files during installation: do it all in one instruction.

npm prune --production

If your Dockerfile installs all dependencies (including dev) to compile the application and then copies node_modules to the final stage unfiltered, you're shipping bundlers, linters, TypeScript types, and testing frameworks to production:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci                     # Installs everything: dev + production
COPY . .
RUN npm run build
RUN npm prune --production     # Removes dev dependencies before copying

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/index.js"]

.dockerignore

The easiest thing to forget and one of the highest-impact optimizations. Without a .dockerignore, you're sending node_modules, .git, logs, and everything in your working directory to the Docker daemon before the build even starts. That slows down the build context transfer and can end up in the image if you have any imprecise COPY . instructions.

A minimal .dockerignore for Node.js projects:

node_modules
.git
.env
*.log
dist
coverage
.DS_Store

Before and after: the complete Dockerfile

Putting it all together — multi-stage builds, BuildKit cache mounts, non-root user, and the optimization techniques from this lesson:

# ❌ BEFORE: 1.2 GB
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

# ✅ AFTER: ~85 MB (93% reduction)
# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY src/ ./src/
COPY tsconfig.json ./
RUN npm run build && npm prune --production

FROM node:20-alpine
RUN addgroup -g 1001 -S appgroup && \
    adduser -u 1001 -S appuser -G appgroup
WORKDIR /app
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

The differences: Alpine instead of full Debian, multi-stage to isolate the build environment, prune to keep only runtime dependencies, non-root user. None of these changes take more than a few minutes — and the result is an image that transfers ten times faster and has a fraction of the attack surface.

That closes the images module. We've gone from knowing what a Dockerfile is to building images that are efficient, secure, and production-ready. Next up is Module 3 — Docker Compose: how to orchestrate multiple containers that need to work together — database, backend, frontend — with a single configuration file and one command.

Never stop coding!

💡 Challenge: Run dive against any image you have over 500 MB. Find the three heaviest layers and identify which technique from this lesson would reduce the size the most. If you can get it under 100 MB, you've got it.

BuildKit in Docker: build secrets, dependency caching, and multi-platform images

Javi Palacios — Thu, 17 Sep 2026 10:30:39 +0000

If you've been using Docker for a while, there's a good chance your builds spend a couple of minutes downloading the exact same packages every single time. npm install, pip install, bundle install. Everything. From scratch. The lockfile hasn't changed. The packages haven't changed. Docker just doesn't know that, and nobody told you it could.

Not a Docker design philosophy about build purity. Just something nobody told you existed.

There's also something we left hanging in the previous lesson: ARG leaves values in the image history, visible to anyone who runs docker history. BuildKit has the real solution for that too.

BuildKit is Docker's modern build engine. It's been available since Docker 18.09 and has been the default backend since version 23.0. If you have Docker installed in 2024 or 2025, it's already active. What you probably haven't set up are the features that make it actually useful.

Checking BuildKit and the syntax pragma

On Docker Desktop (Mac and Windows), docker buildx comes included. On Linux installed from system packages — Arch, Ubuntu, Debian — the plugin is optional and needs to be installed separately:

# macOS and Linux (Homebrew)
brew install docker-buildx

# Ubuntu / Debian
apt install docker-buildx-plugin

# Arch Linux
pacman -S docker-buildx

Verify it's available:

docker buildx version

github.com/docker/buildx v0.34.1 ...

If you're on Docker 23.0 or later — which is any installation from 2023 onwards — BuildKit is already the default backend. Nothing else to enable. If you're on an older version for some reason, you can force it per-session with:

DOCKER_BUILDKIT=1 docker build .

Regardless of version, add this comment as the first line of your Dockerfiles:

# syntax=docker/dockerfile:1

Yes, it's a comment that does something. BuildKit uses "frontends" — versioned Dockerfile parsers with their own independent release cycle. This pragma pins the frontend to the latest stable channel and is what gives you access to modern syntax like --mount in RUN instructions. Without it, Docker uses the version bundled with your installation, which may or may not include everything we're about to use.

Build secrets

Quick recap from the previous lesson: passing secrets through ARG leaves them embedded in the image history, readable by anyone with access to the image. BuildKit build secrets fix this cleanly: the build can read the secret while it needs it, but it never ends up in any layer.

The mechanism has two parts. In the Dockerfile, you mount the secret inside the RUN where you use it — and only there:

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN --mount=type=secret,id=npm_token \
    npm config set //registry.npmjs.org/:_authToken=$(cat /run/secrets/npm_token) && \
    npm ci && \
    npm config delete //registry.npmjs.org/:_authToken
COPY . .
RUN npm run build

In the build command, you tell Docker where the secret comes from:

# From a file
docker build --secret id=npm_token,src=.npmtoken .

# From an environment variable
docker build --secret id=npm_token,env=NPM_TOKEN .

The secret is mounted at /run/secrets/<id> for the duration of that RUN. When the command finishes, it's gone. Not in the layer, not in the history. You can verify:

docker history my-image

IMAGE         CREATED      CREATED BY
a1b2c3d4e5f6  2 hours ago  CMD ["node", "dist/index.js"]
...           ...          RUN --mount=type=secret,id=npm_token npm config set ...

The command shows up. The value doesn't. Exactly what you've been trying to achieve since the Dockerfile security best practices lesson.

SSH agent forwarding

The same mechanism exists for SSH access — useful when a build needs to clone a private repository without keys ever touching the container:

# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
RUN apk add --no-cache git openssh-client
RUN --mount=type=ssh \
    git clone git@github.com:your-org/private-library.git /deps
COPY package*.json ./
RUN npm ci

docker build --ssh default .

--ssh default forwards the host's SSH agent. Keys never touch the container filesystem, never end up in any layer, and once the RUN finishes the access is gone.

Cache mounts

The problem from the opening of this lesson has a solution that's exactly one flag long:

# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run build

That's the whole thing. First run: npm downloads everything from the internet and stores the cache in /root/.npm. Second run — even if you built from scratch, even if you deleted the previous image — the cache is still there. npm finds it, downloads nothing.

The time difference is immediate on projects with any meaningful dependencies:

First run:   2m 21s  (full download from npm)
Second run:  8s      (cache hit, zero downloads)

The cache path changes depending on the package manager, but the pattern is always the same:

# npm
RUN --mount=type=cache,target=/root/.npm \
    npm ci

# pip
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# Cargo (Rust)
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    cargo build --release

# apt (Debian/Ubuntu)
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt update && apt install -y curl

The sharing=locked parameter in the apt example prevents two parallel builds from writing to the cache simultaneously — without it, the apt database can get corrupted if you run concurrent builds.

One honest limitation: the cache lives on the build machine, not in the image. If you add a cache mount, it works great locally, and then you notice CI builds take exactly the same time as before — that's completely normal and doesn't mean you did anything wrong. CI runners are typically ephemeral: each job starts on a clean machine with no prior cache. The fix exists, but it's platform-specific. GitHub Actions, GitLab CI, and most modern providers support persisting BuildKit state between runs. Search "BuildKit cache" followed by your CI platform name.

Multi-platform builds

Building on a Mac with Apple Silicon? Deploying to x86_64? Any Raspberry Pi in the mix? If more than one architecture is in the picture, you've already seen an image that works perfectly on your machine and fails on the server. Or you've been maintaining two separate tags by building it in two different places.

Multi-platform builds in BuildKit solve this: build the image for multiple architectures from a single machine and publish it under the same tag. Docker automatically selects the right one on docker pull based on the host's architecture.

First, create a builder with multi-platform support:

docker buildx create --use --name multi-arch-builder

Then build and push. Multi-platform builds need --push or --output — they can't live in local cache only:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t your-registry/my-app:latest \
  --push \
  .

BuildKit builds images for each platform in parallel. For architectures other than the host's native one, it uses QEMU emulation — which works, but turns your CPU into an actor playing a different CPU, with everything that implies for performance. A 45-second Go build can become an 8-minute one when QEMU translates every instruction on the fly. For compiled languages where build time matters, consider native runners for the target architecture.

Node.js, Python, and other interpreted languages fare much better: the Dockerfile installs a runtime that already exists as a multi-arch image, and the source code doesn't require compilation.

Check what platforms your builder supports:

docker buildx inspect --bootstrap

Name:      multi-arch-builder
Driver:    docker-container
Platforms: linux/amd64, linux/arm64, linux/arm/v7, linux/386, ...

BuildKit is the difference between builds that redo the same work every time and builds that protect secrets, reuse prior work, and run on any architecture. Not an advanced feature for edge cases — just the correct way to build images in 2026.

In the next lesson, we close the images module with the final optimization techniques: distroless images, size analysis with dive, and how to produce production images that contain exactly what they need and nothing else.

Never stop coding!

💡 Challenge: Add a cache mount to the Dockerfile of any project you have. Run docker build twice and compare the install step timing. If the second run isn't noticeably faster, check that the cache path matches the correct location for your package manager.

Git hooks: automating what nobody remembers to do

Javi Palacios — Wed, 16 Sep 2026 08:15:41 +0000

Your project's commit history reads: fix. stuff. wip. more stuff. ok now fixed for real. At some point someone left a comment in a PR: "hey, should we write more descriptive commit messages?" Twelve thumbs up. Zero commits changed.

Because good intentions don't scale. Everyone agrees it's a good idea. Everyone has other things to do. And Git, which has the power to stop any of this, just executes what you tell it — no friction, no judgment, no opinion on whether "wip" adequately describes the two hundred lines you staged.

Git hooks are how you add that opinion to the process. Not as a Confluence doc nobody reads after onboarding, not as a recurring conversation at standup — as scripts that run automatically at specific points in the Git workflow and can stop an operation if something doesn't look right.

What are Git hooks

A hook is a script Git runs before or after specific operations: creating a commit, validating a commit message, sending a push to the remote, receiving changes on the server.

The logic is binary: if the script exits with code 0, Git proceeds. If it exits with anything else, the operation is aborted.

A hook can:

Run a linter against staged files before they become a commit.
Check that the commit message follows Conventional Commits format.
Run the test suite before a push reaches the remote.
Block direct pushes to main on the server.
Trigger a deploy after changes land on a release branch.

Git ships with over twenty defined hook points. In practice, most teams use three or four. Don't lose sleep over the full list.

How hooks work

Hooks live in .git/hooks/. Open that directory in any freshly initialized repository:

ls .git/hooks/

applypatch-msg.sample   post-update.sample      pre-commit.sample
commit-msg.sample       pre-applypatch.sample   pre-push.sample
post-checkout.sample    pre-merge-commit.sample pre-rebase.sample
post-commit.sample      pre-receive.sample      prepare-commit-msg.sample
update.sample

Everything ends in .sample — Git includes them as reference but doesn't run them. To activate a hook:

Remove the .sample extension.
Make it executable.

mv .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

That chmod +x is not optional. Git runs hooks as external processes — if the script isn't executable, Git silently ignores it. No error. No warning. Nothing. Just you, a script that should be running, and a growing suspicion that you've somehow broken your entire Git installation when the actual problem is one missing permission bit.

The script can be written in any language available on your system. The shebang tells Git which interpreter to use:

#!/bin/bash
# Hook: pre-commit — reject commits with TODO in staged files
if git diff --cached --name-only | xargs grep -l 'TODO:' 2>/dev/null; then
  echo "Error: staged files contain TODO comments."
  exit 1
fi
exit 0

The client hooks you'll actually use

Client hooks run on the developer's machine during the commit and push lifecycle.

pre-commit

Runs before Git creates the commit, right when your files are staged. The natural moment for linting and format checks.

Exit 1 → commit aborted.

#!/bin/bash
# Run ESLint only on staged JS/TS files
staged=$(git diff --cached --name-only --diff-filter=ACM | grep '\.\(js\|ts\|jsx\|tsx\)$')
if [ -n "$staged" ]; then
  echo "$staged" | xargs npx eslint
  if [ $? -ne 0 ]; then
    echo "ESLint found errors. Fix them before committing."
    exit 1
  fi
fi
exit 0

commit-msg

Runs after the user writes the commit message but before Git saves it. Receives the path to the temporary file holding the message as its first argument.

Built for format validation:

#!/bin/bash
# Validate Conventional Commits format
commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|style|refactor|test|chore|perf|build|ci|revert)(\(.+\))?: .{1,72}"

if ! echo "$commit_msg" | grep -qP "$pattern"; then
  echo "Commit message doesn't follow Conventional Commits format."
  echo "Example: feat(auth): add OAuth2 support"
  exit 1
fi
exit 0

prepare-commit-msg

Runs before the editor opens, after Git has generated the default message. Good for automatically injecting context into the message — like the issue number from the branch name:

#!/bin/bash
# Prepend issue number from branch name (e.g., feature/GH-123)
branch=$(git symbolic-ref --short HEAD)
issue=$(echo "$branch" | grep -oP 'GH-\d+')

if [ -n "$issue" ]; then
  sed -i "1s/^/[$issue] /" "$1"
fi

Working on feature/GH-456-login-form? Every commit automatically starts with [GH-456] without you typing it.

pre-push

Runs before commits are sent to the remote. The last checkpoint before someone else sees your work:

#!/bin/bash
# Run test suite before push
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Push aborted."
  exit 1
fi
exit 0

⚠️ A slow pre-push hook turns every git push into a waiting game. If the suite takes ten minutes, keep it for CI and use the hook only for fast unit tests.

Server-side hooks

Server hooks run on the remote repository — your own Git server, self-hosted GitLab, or similar setups. GitHub and Bitbucket Cloud don't allow arbitrary server-side hooks.

The relevant ones:

Hook	When it runs	Common use
`pre-receive`	Before accepting any push	Reject pushes to protected branches
`update`	Once per branch being updated	Per-branch validation rules
`post-receive`	After accepting the full push	Notifications, deploys, webhooks

If you're on GitHub, GitLab.com, or Bitbucket, these capabilities are already available as branch protection rules and webhooks — no need to write them from scratch. Hand-written server hooks are the territory of teams running their own Git infrastructure.

The gotcha everyone discovers at the worst moment

.git/hooks/ is not tracked.

The hook you spent twenty minutes writing, testing, and tweaking lives only on your machine. The person who clones the repository tomorrow gets nothing — no hooks, no indication hooks should exist, nothing. Each new developer starts with a clean .git/hooks/ full of .sample files and no knowledge of what they're missing.

Git doesn't share hooks automatically because .git/ is intentionally local — same as .git/config, which stores your personal settings without pushing them to the remote.

If your reaction to this is "so what exactly is the point of hooks if the team doesn't have them?"... that's exactly the right question. The answer is below, and it's not "accept the chaos and keep leaving PR comments about the linter."

Sharing hooks across the team

There are a few approaches. The right one depends on the project.

git config core.hooksPath

The most direct option: store hooks in a versioned directory and tell Git to look there.

# Create a versioned hooks directory
mkdir .githooks

# Write your hook
cat > .githooks/pre-commit << 'EOF'
#!/bin/bash
# hook content here
exit 0
EOF
chmod +x .githooks/pre-commit

# Tell Git to use this directory
git config core.hooksPath .githooks

The catch: every developer who clones the repo has to run that git config manually. Document it in the README and hope people read it, or automate it with one of the tools below.

Husky (Node.js projects)

If the project has a package.json, Husky is the standard. The idea is clean: hooks that install automatically on npm install, just like any other dev dependency. Someone solved the distribution problem, packaged it in 2 KB with zero dependencies, and it runs in ~1ms. Use it.

npm install --save-dev husky
npx husky init

This creates a .husky/ directory with a sample pre-commit hook. Every hook you put there is versioned in the repo and auto-installed the next time anyone runs npm install.

.husky/
  pre-commit     # ← versioned, executable, auto-installed
  commit-msg

As of v9 (current: 9.1.7), configuration is minimal — just a prepare script in package.json:

{
  "scripts": {
    "prepare": "husky"
  }
}

For Node.js projects, this is the lowest-friction path.

pre-commit (any language)

For projects without Node — or when you want access to a catalog of ready-made hooks — pre-commit is the most popular alternative.

# macOS and Linux (Homebrew)
brew install pre-commit

# Ubuntu / Debian
apt install pre-commit

# Arch Linux
pacman -S pre-commit

Configuration goes in .pre-commit-config.yaml, which gets versioned:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
  - repo: https://github.com/psf/black
    rev: 25.3.0
    hooks:
      - id: black

Activate it locally once:

pre-commit install

After that, the pre-commit hook runs on every git commit. Anyone cloning the repo runs pre-commit install once, and .pre-commit-config.yaml tells them exactly which hooks run and at which version.

The advantage over hand-written scripts: you reuse hooks from public repositories — linters, formatters, security scanners — without writing them yourself. The pre-commit ecosystem has hooks for most languages.

lefthook (fast, no runtime dependency)

Lefthook is worth knowing: written in Go, zero runtime dependencies, and can run hooks in parallel.

# macOS and Linux (Homebrew)
brew install lefthook

# Ubuntu / Debian
apt install lefthook

# Arch Linux (AUR)
paru -S lefthook

Configuration in lefthook.yml:

pre-commit:
  parallel: true
  commands:
    lint:
      glob: "*.{js,ts}"
      run: npx eslint {staged_files}
    format:
      glob: "*.py"
      run: black {staged_files}

commit-msg:
  commands:
    validate:
      run: commitlint --edit {1}

Advantage over Husky: works equally well in non-Node projects. Advantage over pre-commit: faster on large repos because it doesn't spin up isolated Python environments per hook.

Node.js project? Use Husky. Everything else? Use pre-commit or lefthook. Want to wire it up manually with core.hooksPath? That works too. All three are valid — the choice comes down to what infrastructure you already have.

A complete example

A team wants linting and commit message validation on a Node.js project:

npm install --save-dev husky lint-staged

npx husky init

cat > .husky/commit-msg << 'EOF'
#!/bin/sh
npx --no -- commitlint --edit "$1"
EOF
chmod +x .husky/commit-msg

lint-staged runs linters only against staged files, not the entire project:

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,ts}": ["eslint --fix", "prettier --write"],
    "*.{css,md}": ["prettier --write"]
  },
  "devDependencies": {
    "husky": "^9.1.7",
    "lint-staged": "^15.0.0"
  }
}

# .husky/pre-commit
#!/bin/sh
npx lint-staged

Every git commit now runs ESLint and Prettier on staged files. Something fails → commit aborted. Every developer on the team has the same hooks from the first npm install. The "have you run the linter?" question disappears from pull request reviews, because the answer is structurally yes.

Bypassing a hook

When it's urgent — and it always is — the --no-verify flag skips all client hooks for a single operation:

git commit -m "hotfix: production is on fire" --no-verify

This doesn't disable hooks permanently. It skips them once. Useful for genuine emergencies.

If you find yourself using it regularly, the hooks are either too slow or too strict for the team's actual workflow. Fix that before --no-verify becomes the first thing everyone types after git commit.

Key concepts from this lesson

A Git hook is a script that runs automatically at specific points in the Git lifecycle.
Hooks live in .git/hooks/ and require execute permissions.
Exit 0 = operation continues. Any other exit code = operation aborted.
.git/hooks/ is not versioned — hooks are local by default.
To share hooks with the team: core.hooksPath, Husky (Node), pre-commit, or lefthook.
--no-verify bypasses client hooks for a single operation.

Hooks solve a specific class of problem: the one where the process depends on someone remembering to run the linter. A ten-line script is more reliable than any number of good intentions and any number of pull request comments that say "hey, could you run the formatter before merging?" Not because the team isn't capable — because nobody should have to remember this in the first place.

Next up: Git worktrees, which let you have multiple working directories of the same repository active at the same time — useful for the moment you're mid-feature and an urgent fix lands in your lap and you'd rather not stash everything and hope nothing breaks.

Never stop coding!

Git submodules: repositories inside repositories without losing your mind

Javi Palacios — Tue, 15 Sep 2026 15:57:08 +0000

You have a project. Inside that project, you need another project. But you don't want to copy it by hand, because every future update will turn into archaeology with diff. You also don't want a normal package dependency, because maybe it's an internal template, a private library, shared documentation, or a theme with its own history.

Then someone says: "use a submodule".

Silence. What does that even mean? Is it a dependency? A folder? Another repository? Why is there suddenly a .gitmodules file staring at you like you summoned something ancient? Good news: submodules are not dark magic. Bad news: they are one of those Git features that punish you if you treat them like a normal directory.

What a Git submodule is

A submodule is a Git repository embedded inside another Git repository. The main repository is called the superproject, which sounds like a comic-book villain but simply means "the repo that contains the other one".

Here is what trips most people up: you see a folder. Git sees a pointer. The main repo does not store the submodule files as its own — it records a note that says: use this other repository, at exactly this commit.

It's saying:

"My project uses vendor/theme, but not just any version of vendor/theme: exactly commit a1b2c3d."

That part matters. A submodule does not point to "the latest version" by default. It points to an exact commit. Git is being strict, yes, but for a reason: it wants anyone cloning your project to get the same state, not "whatever happens to be on main today, good luck in production".

If you read the previous lesson on Git tags, this should feel familiar: Git is very good at pointing to precise places in history. With a submodule, instead of marking a point in your own repo, you're saying which exact point of another repo belongs to this project.

When to use submodules and when to run away

Submodules have a reputation. Some of it is deserved. Some of it comes from people using them to solve problems that were never submodule problems.

Use them when you need to keep two repositories separate, with separate histories, while one still needs to live inside the other:

A shared theme used by multiple static sites.
An internal library that is not published to a package registry.
Common documentation reused by several projects.
A repository of assets or examples that you want pinned to a specific version.

Do not use them as your first option for normal dependencies. If you're in Node, Python, Ruby, Go, or any ecosystem with a decent package manager, use the package manager. That's what it's for. Using submodules where npm install would do is like bringing an excavator to plant basil.

Also avoid them if the team doesn't understand the cost: every submodule is another repository to clone, update, review, push, and coordinate. One or two can be reasonable. Twelve nested submodules are a creative way to turn onboarding into an escape room.

Adding a submodule

Let's use a realistic example: you have a website and want to add a shared theme under vendor/site-theme.

git submodule add https://github.com/example/site-theme.git vendor/site-theme

Git clones that repository into the path you provided:

Cloning into '/home/dev/my-site/vendor/site-theme'...
remote: Enumerating objects: 42, done.
remote: Counting objects: 100% (42/42), done.
remote: Compressing objects: 100% (31/31), done.
Receiving objects: 100% (42/42), done.

Now check the status:

git status

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    new file:   .gitmodules
    new file:   vendor/site-theme

This is the first "wait, what just happened?" moment. Git did not add every file from vendor/site-theme to the main repository. It added two things:

.gitmodules, with the submodule configuration.
A special entry for vendor/site-theme, pointing to a specific commit.

The .gitmodules file looks like this:

[submodule "vendor/site-theme"]
    path = vendor/site-theme
    url = https://github.com/example/site-theme.git

This file is versioned like any other file. When someone else clones your project, Git reads it to know where the submodule lives and where to fetch it from.

Run the diff with the submodule flag and you will see what Git is actually recording:

git diff --cached --submodule

Submodule vendor/site-theme 0000000...a1b2c3d (new submodule)

That a1b2c3d is the submodule commit your main project is recording. It is not recording "the folder". It is recording "this folder must be at this commit".

Commit the change:

git commit -m "feat: add shared site theme submodule"

Cloning a project with submodules

This is the part that gets almost everyone the first time.

You clone a project:

git clone https://github.com/example/my-site.git
cd my-site
ls vendor/site-theme

And the folder is empty. Or almost empty. If you're anything like me when I started, your first instinct was git status followed by staring at the ceiling. Git did not break. It did exactly what you asked: clone the main repository, nothing else.

The painless way is to clone like this from the start:

git clone --recurse-submodules https://github.com/example/my-site.git

That makes Git clone the main repo, read .gitmodules, initialize the submodules, and check them out at the correct commits.

If you already cloned and forgot the flag — because you're human, not a CI pipeline with repressed feelings — run this from the project root:

git submodule update --init --recursive

What each part does:

update checks out the submodule commit expected by the superproject.
--init initializes submodules not yet registered in your local .git/config.
--recursive does the same for submodules inside submodules.

Yes, submodules inside submodules. This is where Git reminds you that you can technically build a Russian doll out of repositories. That doesn't mean you should.

Understanding submodule status

The basic command is:

git submodule status

Normal output:

 a1b2c3d4e5f678901234567890abcdef12345678 vendor/site-theme (v1.2.0)

The hash is the commit currently checked out inside the submodule. The path is where it lives. The bit in parentheses, when present, comes from git describe and usually shows a nearby tag or name.

The important part is the first character:

Prefix	Meaning
space	The submodule is initialized and matches the expected commit.
`-`	The submodule is not initialized. The folder may be empty.
`+`	The submodule is checked out at a different commit than the superproject expects.
`U`	The submodule has merge conflicts. Fun, but not the kind you asked for.

The + prefix is the one that confuses people most at first. It means: "inside the submodule you have one commit checked out, but the main repo expects another". That is not necessarily wrong. It may be exactly what you want if you're updating the submodule. But until you run git add vendor/site-theme in the main repo and commit it, that change is not recorded.

To see the change in a more human form:

git diff --submodule

Submodule vendor/site-theme a1b2c3d..f6e7d8c:
  > Improve button spacing
  > Fix dark mode contrast

Much better than staring at two hex strings hoping one of them eventually starts making sense.

Updating a submodule

Imagine the shared theme has moved forward. There are new commits in site-theme, and you want your project to use one of them.

You can enter the submodule and update it like any Git repo:

cd vendor/site-theme
git fetch
git switch main
git pull

Then go back to the main repo:

cd ../..
git status

Changes not staged for commit:
    modified:   vendor/site-theme (new commits)

That message means: "the submodule now points to another commit". To save that update in the superproject:

git add vendor/site-theme
git commit -m "chore: update site theme submodule"

A more direct option is:

git submodule update --remote vendor/site-theme

This fetches changes from the submodule remote and moves it to the configured remote branch. By default, that is usually the remote HEAD branch. If your team wants the submodule to follow a specific branch, record it:

git config -f .gitmodules submodule.vendor/site-theme.branch main
git submodule update --remote vendor/site-theme
git add .gitmodules vendor/site-theme
git commit -m "chore: track main branch for site theme submodule"

Don't stress about this part if you're just starting. The practical rule is: updating the submodule changes the commit the main repo points to. That change must be added and committed from the main repo.

Working inside a submodule

Here's where it gets interesting. And by "interesting" I mean "this is where people lose an afternoon".

When you run git submodule update, Git usually leaves the submodule in detached HEAD. We've already seen detached HEAD is not the end of the world, but it's also not the place where you want to happily develop like nothing can go wrong.

If you need to modify the submodule, enter it and switch to a branch:

cd vendor/site-theme
git switch main

Make changes, commit, and push inside the submodule:

git add styles/buttons.css
git commit -m "fix: improve button contrast"
git push origin main

Then return to the main repo and record the new submodule commit:

cd ../..
git add vendor/site-theme
git commit -m "chore: update site theme submodule pointer"

The order matters:

Commit inside the submodule.
Push the submodule.
Commit the pointer in the main repo.
Push the main repo.

If you do steps 3 and 4 without pushing the submodule, your main repo will point to a commit that only exists on your machine. For your teammates, that is like receiving a treasure map where the island doesn't exist.

You can ask Git to check this when pushing:

git push --recurse-submodules=check

If any required submodule commit has not been pushed, Git aborts the push. There is also:

git push --recurse-submodules=on-demand

This tries to push the required submodules before pushing the main repo. Useful, but use it knowing what it does. Automating things you don't understand is how incidents get proper names.

Pulling main repo changes when submodules exist

Another common case: someone on the team updates the submodule and pushes the main repo. You pull:

git pull

Git may bring the superproject commit, but your submodule folder can remain at the previous commit. If git status shows the submodule as modified, run:

git submodule update --init --recursive

This command means "put everything where the main repo expects it". It does not blindly update to the latest remote commit; it updates to the exact commit recorded by the superproject.

If your repo uses submodules often, you can configure Git so many operations recurse automatically:

git config submodule.recurse true

Heads up: git clone still needs its own --recurse-submodules. Git had to leave one tiny trap in there. For humility, apparently.

Removing a submodule

Removing a submodule should not be rm -rf vendor/site-theme followed by a short prayer to Linus Torvalds.

The safe recipe is:

git submodule deinit -f vendor/site-theme
git rm -f vendor/site-theme
git commit -m "chore: remove site theme submodule"

What each command does:

git submodule deinit -f vendor/site-theme removes the local submodule checkout and its local configuration.
git rm -f vendor/site-theme removes the submodule entry from the index and updates .gitmodules.
The commit records the change for the rest of the team.

Sometimes local metadata may remain under .git/modules/vendor/site-theme. If you need to clean it manually, be very careful:

rm -rf .git/modules/vendor/site-theme

Read that path again before pressing Enter. rm -rf has no sense of humor. You do. Your filesystem does not.

Best practices for submodules

Submodules work best when the team treats them as what they are: separate repositories coordinated through a pointer.

Practical rules:

Document how to clone the project with --recurse-submodules in the README.
Use URLs everyone can access in .gitmodules; your private SSH URL may work on your machine but fail in CI.
Do not edit submodules in detached HEAD if you want to keep the work. Switch to a branch first.
Push the submodule before the superproject when you've created new commits inside it.
Avoid submodules for normal dependencies if a reasonable package manager exists.
Do not nest submodules unless there is a real need. If you need a diagram to explain how to clone the repo, maybe Git is not the actual problem.

A good sign that a submodule is justified: you can explain why that code needs its own repo, its own history, and its own release cadence. If the explanation is "I saw it on Stack Overflow", pause. Breathe. Reconsider.

Key concepts from this lesson

A submodule is a repository inside another repository.
The main repo does not store the submodule files: it stores a pointer to a specific commit.
.gitmodules records the submodule path and URL, and is versioned with the project.
To clone with submodules, use git clone --recurse-submodules.
If you already cloned, use git submodule update --init --recursive.
Updating a submodule changes the commit recorded by the superproject.
If you work inside the submodule, commit and push there before updating the main repo.

Submodules are useful when you need to coordinate separate repositories without mixing them together. They are not a normal dependency, not a normal folder, and definitely not something you add because it's Friday afternoon and you feel experimental. But when the use case fits, they give you a precise way to say: "this project depends on exactly this other repo, at exactly this commit".

In the next tutorial we'll look at Git hooks, which let you run scripts automatically at specific moments in the Git workflow: before committing, while validating messages, after receiving changes on a server… useful, powerful, and with enough room for someone to turn git commit into an obstacle course. We'll take it slowly.

Never stop coding!

Using AI to learn programming concepts

Javi Palacios — Mon, 14 Sep 2026 16:54:03 +0000

You're reading about recursion. The explanation starts fine: “a function that calls itself.” Fair enough. You keep going. There's a factorial example. Still sort of fine. Then suddenly there's a call stack, a base case, return values unwinding in reverse order, and your brain returns HTTP 500.

So you do the reasonable thing: you ask AI.

Explain recursion to me.

And the AI gives you a correct definition, a correct example, and a correct analogy. Everything is correct. You still don't get it. Fantastic. We have produced documentation with a positive attitude and actionable insights.

The problem isn't that AI can't teach. It can. Very well, actually. The problem is that many people use it like a searchable encyclopedia with a chat box, when for learning programming it works much better as a technical tutor: patient, adaptable, and available at 2 AM, which is when questions actually decide to show up. During the day they hide. Like bugs.

In the previous lesson we looked at advanced context, role, task, and format. Now we'll apply the same idea to something more delicate: learning concepts without settling for an explanation that sounds good but collapses the moment you try to write code.

AI as a tutor, not an oracle

AI should not be the divine voice descending from the cloud to hand you truth in Markdown. If you use it that way, you train yourself to accept answers that sound convincing. And as we saw earlier in the course, a convincing answer is not always a correct one.

For learning, the useful mental model is this: AI is a tutor you can direct.

That changes the conversation. You don't just ask “explain closures” and passively receive. You tell it what you know, what you don't know, what confuses you, and how you want to test your understanding.

Look at the difference:

❌ Explain closures in Python.

That can work, yes. It can also give you a generic explanation that starts well, becomes abstract, and ends with the same outer() and inner() example you've seen in twenty blog posts.

Now try this:

Role: act as a Python mentor for someone learning programming.

Context:
I understand variables, functions, and local scope, but I struggle to understand
why an inner function can remember values from an outer function after the outer
function has finished running.

Task:
Explain closures by connecting them to what I already know. Don't use decorators yet.

Format:
1. Short explanation
2. Realistic analogy
3. Minimal Python example
4. Common mistake
5. One question to check whether I understood it

The second version doesn't ask for “content.” It asks for a learning experience. It's like going to the doctor: “it hurts” doesn't help much; “it hurts here, since yesterday, when I do this” gives someone something to work with.

And yes, you can ask questions that feel too basic. You should, actually.

“Stupid” questions that are not stupid

One of the best things about using AI to learn is that you can ask without the social pressure of looking lost. No teammate looking over your shoulder. No rushed teacher. No senior sighing because you mixed up map() and a for loop. Just you, the question, and a text box.

Use that.

I know this is basic, but: why does Python use indentation instead of braces?

I don't understand what it means for a variable to be "mutable".
Explain it assuming I know what a list is, but not what happens underneath.

I've read the docs about `return`, but I still confuse returning a value
with printing it to the screen. Can you compare them with small examples?

These questions are gold. Not because they're sophisticated, but because they hit the exact place where your brain is stuck. General documentation can't guess that place.

If you're following the Python course from scratch, this approach fits concepts like variables and data types, functions, or lists. Don't just ask “what is a list?” Ask about the specific confusion: “why does append() modify the list but string.upper() doesn't modify the original string?” That's where real learning starts.

A good learning question usually looks like this:

I'm learning [concept].
I already understand [what you know].
I'm confused by [specific blocker].
Explain it using [kind of example that helps you].
Then ask me a question to check whether I understood it.

No ceremony required. You're not submitting a petition to the International Prompt Committee. You're just making it clear where you are and where you fell over.

The Feynman technique with AI

The Feynman technique is brutally simple: if you want to check whether you understand something, try explaining it in your own words. If you can't, you don't understand it yet. If your explanation is hand-wavy, you don't understand it either. And if you explain it using words you couldn't define, your brain has just outsourced the problem.

With AI, this process has one more participant: someone who doesn't get tired of listening to you explain things badly, doesn't sigh when you take your time, and has exercises ready for when you finish.

Recommended flow:

Step 1:
Explain Python generators with a minimal example.

Step 2:
I'll explain it back in my own words. Correct me if there are errors or vague parts:
[your explanation]

Step 3:
Ask me 3 questions to check whether I understood it.
One should be conceptual, one should be code reading, and one should require writing code.

Step 4:
Here are my answers:
[your answers]

Tell me what I understood, what I got wrong, and what I should review.

Notice the important detail: you're not asking for yet another explanation. You're forcing yourself to produce one. That shift costs something. The kind of cost you feel when you've been reading someone else's code for a while and suddenly have to write your own. But that's exactly where learning starts.

Example explanation you might send:

I think a generator is a function that doesn't return all values at once.
It uses yield to pause execution and continue later from the same point.
That helps avoid loading a whole list into memory.

I'm not sure whether the generator remembers local variables between calls or
recalculates them each time.

That last sentence is the gem: “I'm not sure...” Don't hide it. Explicit doubts are anchors. If you leave them out because you're embarrassed, the AI can't help where it actually matters.

The dangerous part comes next: AI can correct you incorrectly. Yes, shocking, a probabilistic tool can make things up. We're not looking for faith here; we're looking for initial feedback. If the explanation matters, verify it against official docs, tests, or real code.

The “but why?” chain

Some concepts stay blurry because you memorize them too high up. You can repeat the sentence, but you don't know what holds it up.

“We use functions to avoid repeating code.” Fine. But why is repeating code bad?

“Because it makes maintenance harder.” Fine. But why?

“Because if a rule changes, you have to change it in several places.” Fine. And what happens if you forget one?

Now we're getting somewhere.

You can use AI to walk down that staircase:

I want to truly understand why code duplication is a problem.
Run a "but why" chain with me.
Don't give me a long explanation at the start: ask me, wait for my answer,
and then go deeper based on what I say.

Or, if you want a single response:

Explain why we reduce duplicated code in programming using a 5-level chain:
1. Simple answer
2. Why that answer matters
3. What problem appears in a real project
4. What bug it could cause
5. What design principle sits underneath

A useful answer might look like this:

1. We avoid duplication so we don't write the same thing several times.
2. It matters because each copy can become outdated.
3. In a real project, a duplicated discount rule might be changed in one endpoint
   but not another.
4. That can make two users receive different prices for the same purchase.
5. The principle underneath is DRY: one rule should have one source of truth.

This turns a textbook phrase into a causal chain. And a causal chain is easier to remember because it has weight. It isn't “DRY because reasons.” It's “DRY because if you duplicate business rules, production eventually sends you a bill with interest.”

AI is especially useful here because it doesn't get tired of your “but why?” A person, by the fourth one, starts looking at the door. AI doesn't. Unfair advantage; use it.

The connection game

Learning programming is not collecting loose definitions. It's connecting ideas.

A Python list is similar to an array in other languages, but not exactly the same. A dict is like an address book where you look things up by name, but it also has internal rules. A pure function is like an honest vending machine: same input, same output. If only all functions were like that. If only vending machines were too.

AI can help you create those connections if you ask explicitly.

I'm learning Python lists.
I already understand variables and `for` loops.

Explain lists by connecting them to:
1. An everyday analogy
2. How they work with a `for` loop
3. How they differ from a string
4. A common beginner mistake

You can also ask for comparisons between technologies:

How is Django's ORM similar to writing SQL directly?
How is it different?
Explain it for someone who knows basic SELECT, INSERT, and WHERE.

Or connections between patterns:

Is Python's `@timer` decorator related to the design pattern called Decorator?
Tell me what they share, where they differ, and where people usually get confused.

These questions work because they don't let the concept float in the air. They tie it to something you already know. Learning this way is like building a bridge: if there is no starting bank, it doesn't matter how pretty the bridge is; it ends in the middle of the river. Very poetic for a programming tutorial.

If you're learning several things at once — say Python, Git, and a bit of Docker — ask for connections between them. AI can help you see that a development environment is not a pile of unrelated tools, but a system where each piece has a job. And if you overdo it until everything seems connected to everything else, don't worry: that's also a phase. It passes. Mostly.

Verify that you understand, not that you nodded

The danger of learning with AI is that explanations often sound very good. Too good. Clean paragraphs, neat structure, confident tone. Your brain reads that and says: “yes, yes, got it.” Sure it did. Your brain also says “I'll just check one quick thing on YouTube,” and we know how that ends.

To know whether you understand, you need to produce something.

Ask for exercises:

Give me 5 progressive exercises about functions in Python.
Don't give me the solutions yet.
Each exercise should check a different concept.

Ask for code reading:

Show me a small code snippet with lists and loops.
Ask me 4 questions about what it prints and why.
Don't reveal the answer until I respond.

Ask it to find errors in your reasoning:

This is my explanation of the difference between `print()` and `return`:
[your explanation]

Point out errors, incomplete parts, and sentences that sound good but are imprecise.

And above all, ask for variations:

Give me a similar exercise, but with a different trap.

That sentence is more powerful than it looks. If you only solve an exercise identical to the example, you may have memorized the visual pattern. A variation checks whether you understood the idea.

Example:

Concept: `return` ends function execution.

Give me 3 code snippets:
1. One where `return` appears inside an `if`
2. One where there is code after `return`
3. One where a function calls another function that returns a value

Ask me what each one prints and why.

This is less comfortable than reading another explanation. But learning programming was never just reading. Reading is looking at the map. Solving exercises is walking. And yes, sometimes you step in mud. That's called software development.

Be careful: AI can help you learn wrong faster

AI accelerates learning. That sounds good, but there's a flip side: it can also accelerate misunderstandings.

If it explains a concept incorrectly and you don't verify it, you can internalize a wrong idea with a lot of confidence. Worse: because the explanation was clear, you'll be less likely to suspect it. It's the educational equivalent of a bug with good naming: it looks respectable until it breaks something important.

Practical rules:

If the concept is basic and general, use AI to understand and practice.
If the concept affects security, concurrency, money, or real data, verify with official documentation.
If there is code, run it.
If you can't run the code, at least ask AI to trace execution step by step, then compare it yourself.
If two answers contradict each other, don't choose the one that sounds more elegant. Investigate.

Useful verification prompt:

I want to check this explanation before trusting it.
Look for possible inaccuracies, dangerous simplifications, or cases where it doesn't hold:

[paste explanation]

Format:
1. What is correct
2. What is imprecise
3. Example where the explanation fails or needs nuance
4. Corrected version in 5 lines

You can also ask it to cite documentation, but remember: a made-up citation still looks like a citation. If it matters, open the real docs. Yes, in a browser. I know, very medieval.

Template for learning any concept

Save this template and use it when a concept refuses to land:

Role: act as a patient and precise technical mentor.

Context:
I'm learning [concept].
I already understand [previous knowledge].
I'm confused by [specific blocker].
I'm using [language/tool] and want examples in that context.

Task:
Help me understand the concept progressively.
Do not assume I understood it until I can explain it and solve an exercise.

Format:
1. Explanation in 5-7 lines
2. Realistic analogy
3. Minimal example
4. Counterexample or common mistake
5. Comprehension question
6. Small exercise without solution

And after answering the exercise:

This is my solution:
[your solution]

Evaluate it using this format:
1. What is correct
2. What is wrong or incomplete
3. What concept my answer proves I understood
4. What concept I should review
5. A similar exercise with one variation

The key is closing the loop: explanation, production, feedback, variation. Without that last part, it's easy to confuse familiarity with understanding. Familiarity is “this rings a bell.” Understanding is “I can use it when the example changes.” Not the same thing, even if your brain tries to sell you the bundle.

Key concepts from this lesson

Use AI as a directed tutor, not an oracle
Basic questions are valuable when they name the exact confusion
The Feynman technique works best when you explain and ask for correction
The “but why?” chain turns memorized phrases into causal understanding
The connection game ties new concepts to previous knowledge
To verify understanding, produce something: explain, read code, write code, or solve exercises
Clear explanations can still be wrong; verify important claims
A good learning session ends with feedback and a variation of the exercise

💡 Challenge: Pick a concept that still feels uncomfortable — recursion, closures, mutability, return, anything — and use the final template. Don't move to the next topic until you've explained the concept in your own words and solved a variation of the exercise.

Learning with AI is not about receiving faster answers; it's about building a smarter practice system. In the next lesson we'll get into prompts for code generation, and the bar goes up: understanding an explanation won't be enough anymore. You'll need to ask for verifiable code without letting AI turn a small function into a cathedral of boilerplate.

Never stop coding!

Context, role, task, and format: advanced application

Javi Palacios — Thu, 10 Sep 2026 14:37:12 +0000

Here's how it goes: you discover RCTF, try it out, and something clicks. The AI stops handing you vague garbage. You're sold on it. Then the next day you ask it something real — a weird bug, a half-built feature, a module that needs structure — and it falls flat. Same framework, same four letters, completely hollow answer.

Was RCTF a lie? Do you need more acronyms? Are we three lessons away from a full methodology with a keynote, a certification program, and a branded water bottle?

No. The framework is fine. The problem is that last lesson we used it like a form to fill out. This lesson is about using it the way you'd actually use it at work: with real context, iteration, and formats that give you something you can act on — not just a well-formatted nothing.

If the framework isn't fresh in your head, go back to the prompt core principles lesson. This lesson assumes you already know what role, context, task, and format mean.

The mistake: treating RCTF like a form

A prompt can include RCTF and still be bad. That's important.

Look at this:

Role: act as a senior backend developer.
Context: I have an API.
Task: help me improve it.
Format: give me a list.

It has all four letters. It also has the precision of a weather report written by someone glancing out the window: “there appears to be sky.”

The role is too generic. The context doesn't say stack, problem, constraints, or goal. The task has no useful verb. The format asks for a list, but defines no criteria. It's RCTF in name only.

Now compare it with this:

Role: act as a backend engineer specialized in REST APIs with Node.js.

Context: I'm maintaining an Express API that manages orders.
Stack: Node.js 22, Express, PostgreSQL, zod for validation, and Vitest.
Problem: the POST /orders endpoint has too much logic in the controller:
it validates input, calculates discounts, writes to the database, and emits events.
I want to refactor without changing behavior because this is already in production.

Task: propose a refactor plan in small steps. Do not write code yet.

Format:
1. Diagnosis of mixed responsibilities
2. Safe 4-6 step plan
3. Risks for each step
4. Tests I should add before touching code

Same structure. Completely different result.

It's not about length. Each part removes an assumption. And every assumption the AI doesn't have to make is one fewer ticket in the nonsense lottery. Context is almost always where most of them pile up.

Rich context doesn't mean your life story

Context is the most important part of RCTF, and also the easiest one to ruin. People often jump from “I give no context” to “here's half the company in Markdown.” Neither extreme helps.

Rich context isn't long context. It's relevant context.

A good context block answers these questions:

What are you building?
What stack or tools are you using?
What exact area are you touching?
What constraints must the solution respect?
What have you already tried?
What does “good” mean in this case?

Project example:

Project context:
I'm working on an e-commerce backend with Django 5 and Django REST Framework.
The database is PostgreSQL 15. We use Redis for cache and Celery for async jobs.
The code has type hints, tests with pytest, and the goal is to avoid breaking
compatibility with the public API.

Relevant domain:
- orders/: Order, OrderItem, Coupon
- products/: Product, Category, Inventory
- users/: CustomUser, Address

Important constraint:
I cannot change the endpoint contract because published mobile apps consume it.

This isn't a documentation dump. It's the minimum map the AI needs so it doesn't propose something that breaks production in sentence two.

Don't overthink it. Keep a base context block for the project and adapt it per task. Think of it like an .env.example file: not the actual secrets, just enough structure that you're not starting from scratch every time.

Project context gets you in the building. Code context puts you in the right room.

Code context: the bug doesn't live alone

When you ask about a bug, project context helps, but code context does the heavy lifting.

A decent debugging prompt should include four pieces:

When asking for bug help, include:
1. The relevant code
2. The failing test or reproduction steps
3. The full error message
4. What you expected vs what actually happened

The fourth point sounds obvious until you forget it. The AI can read the error, but it can't infer your intent. “This fails” isn't a diagnosis; it's a scream. Understandable, yes. Useful, less so.

Weak example:

This function breaks for users without email. Fix it.

Useful example:

Role: act as a senior Python developer.

Context:
This function normalizes user data imported from CSV. Some users don't have an
email because they come from old records. In that case I want to return None,
not raise an exception.

Code:
````python
def normalize_email(user):
    return user["email"].strip().lower()
````

Error:
KeyError: 'email'

Expected behavior:

- If user["email"] exists and contains text, return it normalized
- If it doesn't exist or is empty, return None
- Keep the function small and easy to test

Task:
Propose the implementation and 3 pytest tests.

Format:

1. Final code
2. Tests
3. Brief explanation of the covered cases

The AI doesn't get better because it has become “smarter.” It gets better because it no longer has to guess the function contract. You gave it the walls of the room before asking it to arrange the furniture.

Iterate: a conversation, not a vending machine

Here's the mental model most people skip: the AI is not a vending machine. You don't drop in a prompt, wait for the answer to fall out, and walk away with your solution. That's how you get responses that technically address the question and solve nothing.

The next mental shift is this: don't try to solve everything in one giant prompt.

AI works better when the conversation moves in rounds. The same way you'd work with a person: first define direction, then get into details, then review, correct, and test. You don't tell a teammate: “design, implement, test, document, optimize, and deploy this system; I'll be back in ten minutes.” Well, maybe at some companies. And then things happen.

An iterative flow could look like this:

Round 1:
Propose a structure for implementing user registration in Flask.
Architecture and files only, no code.

Round 2:
Now implement the User model and validation layer.
Keep the code simple and testable.

Round 3:
Write tests for the happy path and these error cases:
- invalid email
- duplicate email
- password too short

Round 4:
The duplicate email test fails with this error: [paste error]
Diagnose the cause before proposing changes.

Round 5:
Refactor the validation to reduce duplication without changing behavior.

This avoids two classic problems: huge responses that mix incompatible decisions, and changes you can't evaluate because everything happened at once.

Practical rule: each round should change one main thing. Architecture. Implementation. Tests. Debugging. Refactor. If you mix everything, you won't know which part worked and which part just smuggled a gremlin into your repository.

Format: ask for a response you can actually use

Format isn't decoration. It's the interface between the AI's response and your workflow.

If you ask “explain this,” you get an explanation. If you ask “give me a plan with risks and tests,” you get something you can execute. Sounds small, but it's the difference between reading content and moving work forward.

Useful formats for development:

For code generation

Format:
1. Implementation code
2. Example usage
3. Minimal tests
4. Technical decisions and trade-offs

For debugging

Format:
1. Likely root cause
2. Why it happens
3. How to confirm it
4. Minimal fix
5. How to prevent it in the future

For learning a concept

Format:
1. One-sentence definition
2. Realistic analogy
3. Minimal code example
4. Common mistake to avoid

For comparing options

Format:
Table with columns:
- Option
- When to use it
- Advantages
- Risks
- Recommendation for my case

The trick is asking for the format that matches your next action. If you're deciding, ask for a comparison. If you're implementing, ask for steps and tests. If you're learning, ask for an explanation, analogy, and gotcha. The AI doesn't know your next move unless you tell it.

Templates you can reuse

Here are three practical templates. Not to copy like scripture, but to adapt.

Reviewing code

Role: act as a senior developer specialized in [language/framework].

Context:
[What the code does]
[Relevant stack]
[Constraints: don't change public API, keep compatibility, etc.]

Code:
[paste code]

Task:
Review the code for readability issues, potential bugs, and edge cases.
Do not refactor yet.

Format:
1. 3-line summary
2. Issues ordered by impact
3. For each issue: why it matters and how you would confirm it
4. Questions that must be answered before touching code

Designing an implementation

Role: act as a pragmatic software engineer.

Context:
[Feature you want to build]
[Stack]
[Constraints]
[What already exists]

Task:
Propose a simple implementation design. Prioritize small, verifiable changes.
Do not write code yet.

Format:
1. Assumptions
2. Proposed design
3. Files you would touch
4. Step-by-step plan
5. Tests needed
6. Risks and alternatives

Asking for a technical explanation

Role: act as a technical mentor.

Context:
I'm learning [concept]. I already understand [previous knowledge], but I'm stuck on [specific blocker].

Task:
Explain [concept] by connecting it to what I already know.

Format:
1. Short explanation
2. Analogy
3. Minimal example
4. Counterexample
5. Question to check whether I understood it

A good template doesn't replace thinking. It removes mental boilerplate so you can focus on the actual problem. Like editor snippets: helpful when you know what you're inserting, dangerous when you fire them blindly.

What not to put in context

Less fun, but necessary: not all context should be shared.

Don't paste:

API keys
tokens
passwords
real personal data
company secrets
full database dumps
proprietary code if your tool or policy doesn't allow it

Yes, the AI “needs context.” No, it doesn't need your production token. That sentence belongs on a mug, right next to “don't run commands you don't understand.”

If you need to show data, anonymize it:

{
  "user_id": "user_123",
  "email": "user@example.com",
  "plan": "pro"
}

And if the problem depends on a sensitive value, describe it:

The token exists and has a valid JWT format, but the backend returns 401.
I can't share the real token; I can share the anonymized header and claims.

Context quality isn't measured by how many secrets you expose. It's measured by how many assumptions you remove without creating a new problem.

Key concepts from this lesson

RCTF doesn't help if each block is generic; each part must reduce assumptions
Rich context means relevant context, not long context
For bugs, include code, reproduction, error, and expected behavior
AI conversations work better in small rounds than in one giant prompt
Each round should change one main thing
Format should connect the response to your next action
Templates help, but they don't replace thinking
Never share secrets, tokens, or real personal data as “context”

💡 Challenge: Take a real prompt you've used for code help and turn it into a three-round conversation: (1) context and diagnosis, (2) solution proposal, (3) tests or verification. In each round, specify a different format based on what you need to do next.

RCTF is no longer just a checklist: it's a way to direct a technical conversation. In the next lesson we'll look at how to use AI to learn programming concepts without getting stuck with explanations that sound good but collapse under pressure — because real understanding isn't nodding at a convincing answer, it's being able to spot when someone is selling smoke with nice syntax.

Never stop coding!

Search in Vim: find text without losing your flow

Javi Palacios — Wed, 09 Sep 2026 11:33:00 +0000

You're inside a 400-line file. You need to find where userId is used, but your fingers start the classic ritual: j, j, j, j, look around, j, j, k because you overshot, sigh, repeat. Where was that variable? Why are there three similar blocks? Who wrote this endless function? Ah. You did. Always more fun when the culprit is you.

Vim doesn't want you wandering through files like you're searching for your keys in the dark — room by room, hand on the wall. It wants you to jump straight to the place. Search isn't a secondary tool: it's a way to move.

Two kinds of search

In Vim there are two search families worth separating early:

Search inside the current line: f, F, t, T
Search across the file: /, ?, n, N, *, #

The first helps you move quickly inside one specific line. The second lets you jump between matches across the whole file.

If you're coming from Visual mode, this fits nicely with what you already know: search can become part of a selection. Press v, search with /, and Vim extends the selection up to the match. Not magic; just Vim's grammar doing overtime.

Searching for characters inside a line

Start with a line like this:

const totalPrice = calculatePrice(quantity, unitPrice);

Place the cursor at the beginning of the line, on the c in const.

f{character} finds the next character on the same line and places the cursor on top of it:

fp

That command jumps to the p in totalPrice.

f stands for find. Easy enough. For once, Vim didn't call it zq or something that looks like a router spell.

The backward version is F{character}:

F=

It searches for = to the left from wherever you are.

The important difference comes with t and T.

t{character} searches forward, but stops right before the found character:

t(

In the line above, that leaves you right before the ( in calculatePrice(...).

T{character} does the same thing backward: it searches to the left and stops just after the found character.

The mental table looks like this:

Command	Direction	Where the cursor lands
`f{c}`	Forward	On the character
`F{c}`	Backward	On the character
`t{c}`	Forward	Before the character
`T{c}`	Backward	After the character

Why does t exist if we already have f? Because sometimes you don't want to land on the character; you want to stop right before it so you can operate precisely.

For example, to delete up to but not including the opening parenthesis:

dt(

From const totalPrice = calculatePrice..., that deletes from the cursor up to just before (. If you used df(, it would also delete the parenthesis. Sometimes you want the door; sometimes you want the doormat.

Repeating character search with ; and ,

After using f, F, t, or T, repeat the same search with ;:

f,
;
;

Imagine this line:

createUser(name, email, role, isActive);

f, jumps to the first comma. Each ; jumps to the next comma. Tiny command, constant real-world use.

To repeat in the opposite direction, use ,:

Yes, ; goes forward and , goes backward. Is it intuitive? Sort of. Will you end up using it without thinking? Also yes. Vim has many things that feel like private jokes at first and later become muscle memory.

Searching across the file with /

To search forward across the file, use /:

/userId

Press Enter and Vim jumps to the next occurrence of userId.

This changes how you move. Instead of counting lines or hammering j, you type what you're looking for. If the file is a city, / is taking the subway. You're not walking door to door checking nameplates.

To search for the next occurrence, press n:

To go back to the previous occurrence, press N:

Important detail: n repeats the search in the same direction you originally used. If you searched with /, n goes forward. If you searched with ?, n goes backward.

Searching backward with ?

? is like /, but it searches backward:

?userId

After that:

n keeps searching backward
N reverses direction and searches forward

This sounds like a tongue twister until you've used it twice. Short rule: n repeats, N reverses.

If you ever press n and the cursor goes the “wrong” way, Vim isn't being dramatic. The last search probably started with ?. It happens. Breathe, press N, move on.

Searching the word under the cursor with `*` and `#`

This is one of those commands you should pick up early because it removes a lot of noise.

Place the cursor on a word and press *:

Vim searches forward for the next occurrence of that whole word.

Press # and it does the same thing backward:

Typical case: you're on userId, press *, then walk through its uses with n. No typing the word, no opening a side panel, no reaching for the mouse like you're asking the editor for permission.

There are also g* and g#, which search partial matches. The difference:

Command	What it searches for
`*`	Whole word forward
`#`	Whole word backward
`g*`	Partial match forward
`g#`	Partial match backward

If you're on user, * searches for user as a whole word. g* may also find userId, currentUser, or users, depending on the text. Useful, but be careful: searching too broadly is like asking for “some food” and getting the supermarket inventory.

Search highlighting: hlsearch, incsearch, and noh

When you search, Vim can highlight all matches. That's controlled by hlsearch:

:set hlsearch

From then on, each search leaves matches highlighted.

You can also enable incsearch:

:set incsearch

With incsearch, Vim shows matches while you type the pattern. Type /use, and before pressing Enter you already see where you'll land. Very useful for avoiding blind searches.

Now comes the classic Vim moment: you enable hlsearch, search for something, finish the job, and the file stays highlighted like someone attacked your screen with a marker and too much coffee.

To clear the current highlight without disabling the option, use:

:nohlsearch

Or the short version:

:noh

This doesn't turn hlsearch off forever. It only clears the current search; the next search will highlight again. That's what you want most of the time.

Case sensitivity and precise searches

You can force a case-insensitive search with \c:

/userid\c

That finds userid, userId, USERID, and so on.

You can force a case-sensitive search with \C:

/userId\C

That searches exactly for userId, respecting uppercase and lowercase letters.

There are global options like ignorecase and smartcase, but you don't need to go there yet. For now, \c and \C give you local control when you need it. Not everything needs to become permanent configuration. Yes, even in Vim.

Search and replace: first contact

Full substitution deserves its own lesson later, but you need the basics here because substitution is tied closely to search.

To replace on the current line:

:s/var/let/g

That changes every var to let on the current line.

To replace across the whole file:

:%s/var/let/g

The % means “the whole file”. The final g means “all occurrences on each line”, not just the first one.

And here's the version you should use when you're not 100% sure:

:%s/var/let/gc

The c asks for confirmation at each change.

Global replacements without confirmation are fine when you know exactly what you're doing. When you don't, it's like using a chainsaw to open a cardboard box: technically it works, but you'll spend a while explaining the result.

Search as motion

The most powerful thing about search in Vim isn't finding text. Every editor can do that. The powerful part is that search is also a motion.

That means you can combine it with operators from Normal mode's grammar:

d/userId

That deletes from the cursor to the next occurrence of userId.

You can also use searches after entering Visual mode:

v/error

That selects from the cursor to the next occurrence of error.

This is where Vim stops feeling like a list of isolated commands and starts behaving like a small language: operator + motion + repetition. Search isn't “find text”; it's telling the cursor where the next destination is.

Key concepts from this lesson

f{c} and F{c} search for a character on the line and land on it
t{c} and T{c} search for a character but stop before or after it
; repeats the last character search; , repeats it in the opposite direction
/pattern searches forward; ?pattern searches backward
n repeats the search; N reverses direction
* and # search for the word under the cursor forward or backward
:noh clears the current highlight without disabling hlsearch
:%s/old/new/gc replaces across the file with confirmation
Search also works as a motion inside Vim's grammar

💡 Challenge: Open a real code file and practice without using arrows or j/k for long movements. Search for a variable with *, walk through its uses with n and N, jump between commas with f, and ;, and try a safe replacement with :%s/old/new/gc using names you can undo without drama.

You now know how to move through a file without walking line by line. In the next lesson we'll cover marks and jumps: how to leave “bookmarks” inside code and return to previous positions without depending on your memory, which is already busy remembering passwords, commands, and why you opened that browser tab.

Never stop coding!

Releasing new versions of our projects using Git tags

Javi Palacios — Tue, 08 Sep 2026 08:29:47 +0000

We're learning a lot of new things to master Git, but until now we haven't said anything about the versions of our projects. We know that you are very advanced in your project and thanks to Git you are working in a more efficient way. You are about to publish the version 0.1 of your project, so people can try it and leave their opinions, but… How the heck we create a new version of our software in Git? Let's go to it!

In Git there is a function to add tags to our commits, which are only a few pointers (like HEAD or each of the branches, as we saw before), this allows us to reference a commit that we want to be able to locate and access it easily. We can actually create tags for any commit we want to locate quickly once time has passed, but it's true that this function is generally used to launch versions of our applications.

FYI: There are two types of tags, annotated and lightweight tags.

Lightweight tags

First we will focus on the lightweight tags, which are the easiest to learn. This type of tags is usually used to locate a specially relevant commit but not a release of a new version. Why? Because you can only add a label with a name and this doesn't seem very useful, isn't it? It's a kind of reminder, usually a temporary one.

If you want to add the tag to the most recent commit just run the git tag v0.1 command, and if we use the git log --oneline --decorate command we'll see that now our HEAD also has the tag: v0.1 pointer; if we want to add a tag to a previous commit you can also do it, either through the hash of the commit (the code that references the commit located first in the log command) or, as we've learned to do, referencing it in a relative way from the most recent commit (HEAD), like: git tag v0.1 HEAD~2.

Annotated tags

In simple words, an annotated tag is something like a commit as it's treated as an object by Git; in this type of tags we can add a message that explain the reason for having added that tag, in addition, the date it was added and who added it will be saved; that's why it's great for our code versioning, since more information is stored and in the message we can write what are the changes that this new version adds.

The command is very similar to the one we have already learned, but adding some parameters. If we want to write a short message, we can do it as in commits: git tag -a v0.1 -m "Testing Git tags" but if you want to write a longer message, which is recommended, just write git tag -a v0.1 so that Git opens us the text editor that we've configured previously to write everything we want. Logically we can also add annotated tags for previous commits: git tag -a v0.1 -m "Testing Git tags" HEAD~2 easy peasy, right?

Listing tags

We can also get a list of all added tags, and the easiest way is through the git tag command. So easy for you guys, huh? Well, what if you already have a mature development and you have many added versions? Holy shit! That list would be very long! But fortunately there's a way to filter the results. If we want to filter the added tags of the 0.* versions we could execute the git tag -l "v0.*" command.

Getting more information about a tag

If we've added an annotated tag, with the git show v0.1 command we can see all the information related to the tag but also with the commit to which it refers; if we've added a lightweight tag, then we'll only get information about the commit to which it refers because from the tag there would be no information to obtain.

Removing tags

At any time we can delete a tag, whether it's an annotated tag or not, with the same command: git tag -d v0.1. This command doesn't need more explanation, isn't it?

Sending a tag to a remote node

If you want to send a certain tag to a remote node (if you do not know what a remote is, take a look at Creating our first repository on GitHub) you can do it in the same way as we'd send a new branch: git push origin v0.1 and if you want to send more than one tag you can execute the command git push origin --tags to send them all with a single command.

Working with tags on remote nodes

When sending tags to remote nodes like GitHub or GitLab we offer users who visit our projects the information that a new version was released but also that they can download it easily, and for convenience it's created automatically. In GitHub, for example, when a new tag is sent, it obviously appears in the section of tags, but also in the releases one, therefore create a new version of our application so that users can download it is a quick and easy task.

Now you can no longer say that you've not shared with the world a version of your application (I hope an open source application) because you didn't know how to do it.

Never stop programming!

Defining functions in Python: def, parameters, and return

Javi Palacios — Fri, 04 Sep 2026 10:56:54 +0000

You copy three lines of code. Then three more. Then the same three again, but with a different number. At first it feels productive. Ten minutes later your file looks like a haunted photocopier: lots of repetition, very little intention, and every tiny change has to be made in four different places because apparently we enjoy suffering.

That's where functions come in. Not as some academic ritual with fancy terminology, but as a way to tell Python: "this operation has a name; run it whenever I ask."

What is a function?

A function is a reusable block of code. You give it a name, put instructions inside it, and later you execute that block by calling the function.

Think of a coffee machine. You don't want to manually repeat every step each morning: grind beans, heat water, press button, stare into the void while life compiles. You want to press make_coffee() and let the process happen. A function is that: a name attached to a sequence of steps.

In the previous lesson you worked with lists and methods like append() and remove(). If you think about it, you've already been using functions constantly: print(), len(), range(). The difference now is that you're going to create your own.

Your first function with def

In Python, you define a function with the def keyword:

def greet():
    print("Hello, Python")

This defines the function, but it doesn't run it yet. It's like putting a recipe in a drawer: it exists, but nobody is cooking.

To execute it, call the function by name with parentheses:

def greet():
    print("Hello, Python")

greet()

Hello, Python

The basic structure looks like this:

def function_name():
    # Function body
    statement_1
    statement_2

Two details matter:

The def line ends with :
The function body is indented

If you forget the indentation, Python complains. And this time Python is right. Indentation tells Python which code belongs inside the function and which code is outside. It's not decoration; it's syntax.

Why functions matter

Look at this code:

price = 25
tax = price * 0.21
total = price + tax
print(total)

price = 40
tax = price * 0.21
total = price + tax
print(total)

price = 99
tax = price * 0.21
total = price + tax
print(total)

It works. Duct tape on a leaking pipe also works for a while. That doesn't make it architecture.

The issue isn't that the code is long; the issue is that the same idea is repeated. If the tax rate changes tomorrow, you have to update it everywhere. Miss one place and congratulations: you've created an accounting bug, which sounds boring until it bites.

With a function:

def calculate_total(price):
    tax = price * 0.21
    total = price + tax
    print(total)

calculate_total(25)
calculate_total(40)
calculate_total(99)

30.25
48.4
119.79

Now the logic lives in one place. That's the DRY principle: Don't Repeat Yourself. Not because repetition is morally wrong, but because repetition multiplies the number of places where bugs can hide.

Parameters and arguments

In this function:

def calculate_total(price):
    tax = price * 0.21
    total = price + tax
    print(total)

price is a parameter. It's the variable the function expects to receive.

When you call the function:

calculate_total(25)

25 is an argument. It's the actual value passed into that parameter.

The distinction sounds like quiz material until you need to explain code precisely:

Parameter: the name in the function definition
Argument: the value sent when calling the function

Like a reserved seat versus the person sitting in it. The seat is the parameter; the person is the argument. If you're like me when I started, you'll call everything a parameter for a while. You'll survive. Python won't confiscate your keyboard.

You can define multiple parameters:

def show_user(name, age):
    print(f"{name} is {age} years old")

show_user("Ana", 34)
show_user("Luis", 28)

Ana is 34 years old
Luis is 28 years old

Order matters: Python assigns the first argument to the first parameter, the second argument to the second parameter, and so on. In the next lesson we'll look at more flexible ways to call functions, but for now keep the simple rule: order wins.

return: giving a value back

So far our functions print things. That's fine for seeing output, but useful functions usually return a value so the rest of your program can keep working with it.

That's what return is for:

def add(a, b):
    return a + b

result = add(5, 3)
print(result)

The difference between print() and return is massive:

print() displays something on the screen
return gives a value back to the code that called the function

This matters. print() is like saying something out loud. return is like handing someone the tool they need to continue the job. One creates output; the other lets your program move forward.

Look at this example:

def create_message(name):
    return f"Hello, {name}"

message = create_message("Marta")
print(message.upper())

HELLO, MARTA

Because the function returns a string, you can store it, transform it, put it in a list, compare it, whatever you need. If it only printed the string, the value would disappear into the terminal like tears in production logs.

return exits the function

When Python reaches a return, it leaves the function immediately:

def classify_age(age):
    if age < 18:
        return "minor"

    return "adult"

print(classify_age(15))
print(classify_age(30))

minor
adult

If age is less than 18, Python returns "minor" and doesn't continue running the rest of the function. This lets you write clearer functions, especially when you want to handle simple cases early and leave the general case at the end.

Don't stress about patterns yet. For now, understand this: return doesn't just send a value back; it also marks the exit.

Functions that return None

In Python, every function returns something. If you don't write a return, the function returns None automatically.

def greet(name):
    print(f"Hello, {name}")

result = greet("Nora")
print(result)

Hello, Nora
None

Feeling like "wait, I didn't ask for that None"? Fair. Python does it anyway.

None means "no value here". It's not 0, not "", not False. It's its own thing: a special value that represents the absence of a useful result.

This usually appears when a function performs an effect — like printing to the screen — but doesn't return data for the rest of the program to use. Later, when you start writing larger programs, the difference between "doing something" and "returning something" becomes extremely important.

Function names

Function names follow the same convention as variables: snake_case.

def calculate_discount(price, percentage):
    return price - (price * percentage / 100)

The name should explain what the function does. Don't be mysterious with your future self. Your future self is not an archaeologist looking for a side quest.

def c(p, x):
    return p - (p * x / 100)  # ❌ Too cryptic


def calculate_discount(price, percentage):
    return price - (price * percentage / 100)  # ✅ Clear intent

A good rule: if you have to read the function body to understand why the function exists, the name probably needs work.

A practical case: simple calculator

Let's build a tiny calculator using functions. No interface, no strange menus, no eval() — let's not summon demons for sport.

def add(a, b):
    return a + b


def subtract(a, b):
    return a - b


def multiply(a, b):
    return a * b


def divide(a, b):
    if b == 0:
        return "Cannot divide by zero"

    return a / b

print(add(10, 5))
print(subtract(10, 5))
print(multiply(10, 5))
print(divide(10, 5))
print(divide(10, 0))

15
5
50
2.0
Cannot divide by zero

Each function has a clear responsibility. add() adds. subtract() subtracts. divide() divides and protects the problematic case. The code is simple, but it already has structure.

Could you write all operations one after another instead? Of course. You could also store all your socks in the oven. The question isn't whether it can be done; the question is how much you'll suffer when the program grows.

Key concepts from this lesson

A function is a reusable block of code with a name
def defines a function; calling the function executes its body
Parameters live in the definition; arguments are the values sent when calling
return gives a value back and exits the function
If a function has no return, it returns None
print() displays information; return lets you keep using the value
Function names should use snake_case and describe intention
Functions reduce duplication and make code easier to change

💡 Challenge: Create four functions: add(a, b), subtract(a, b), multiply(a, b), and divide(a, b). Then create a fifth function, show_result(operation, result), that prints a message like "Addition: 15". Test every operation with several numbers, including division by zero.

Functions are the first serious step toward modular code. You're no longer writing an endless sequence of instructions; you're naming ideas, separating responsibilities, and building pieces you can reuse. In the next lesson we'll go deeper into default parameters, keyword arguments, *args, and **kwargs — the part where functions stop being a door and become a Swiss Army knife.

Never stop coding!

Advanced Dockerfile instructions: ARG, ENV, ENTRYPOINT and more

Javi Palacios — Wed, 02 Sep 2026 08:49:57 +0000

Most Dockerfiles have a few lines that everyone copies from an example that worked once and never questions again. ENTRYPOINT and CMD near the bottom. ARG and ENV somewhere near the top. The container starts, the app runs, and nobody asks too many questions.

Until it breaks. Or until someone on the team notices the API key getting passed through ARG — which shows up in the image history for anyone to read — or asks why the container ignores the command you pass to docker run. That conversation should have happened earlier. This lesson is it.

ARG vs ENV

ARG or ENV? Which one persists into the container? Which one disappears after the build? Can you combine them? Does the order in the Dockerfile matter? They look similar — both define variables, both accept a name and an optional default value — but they exist at completely different moments in the Docker lifecycle.

ARG defines a variable that only exists during the build process. Once the image is built, it's gone. The container that runs from that image never sees it. Use ARG for things that affect how the image is built: the Node version, the app version string, a compile-time flag.

ENV defines an environment variable that persists into the running container. Use ENV for anything your application needs at runtime.

ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine

ARG APP_VERSION=1.0.0
ENV APP_VERSION=${APP_VERSION}

WORKDIR /app
COPY . .
RUN npm ci
CMD ["node", "index.js"]

NODE_VERSION only exists long enough to pick the base image. After that, it's gone. APP_VERSION is explicitly bridged from ARG to ENV — that's how a build-time value makes it into the running container.

You can override ARG at build time, and ENV at runtime:

# Override ARG during build
docker build --build-arg NODE_VERSION=22 -t my-app .

# Override ENV when running
docker run -e APP_VERSION=2.0.0 my-app

The security gotcha you need to know about

ARG is not a safe place for secrets. Values passed through ARG end up in the image history:

docker history my-app

IMAGE         CREATED       CREATED BY
abc123def456  2 hours ago   CMD ["node", "index.js"]
...           ...           ARG API_KEY=s3cr3t          ← right there

If you've passed an API key, token, or any credential through ARG, it's recoverable from the image by anyone who can pull it. This is covered in detail in Dockerfile security best practices — if you skipped that one, it's worth going back.

The rule: build-time secrets to BuildKit build secrets (next lesson). Runtime secrets to environment variables injected by your secrets management system, never hardcoded in the Dockerfile.

ENTRYPOINT vs CMD

If you're like most people when they first encounter this, you've copied those lines from Stack Overflow, seen that sometimes both appear and sometimes only one, and assumed Docker has its quirks. It doesn't. It has concrete rules, and once you understand them everything clicks.

CMD defines the default command a container runs. It's fully replaceable — pass a different command to docker run and CMD is ignored entirely.

ENTRYPOINT defines the executable that always runs when the container starts. You can't override it with a regular argument — you need --entrypoint explicitly.

When you use both, CMD provides the default arguments to ENTRYPOINT.

# CMD only — fully replaceable command
FROM ubuntu:22.04
CMD ["echo", "hello world"]

docker run my-image               # → "hello world"
docker run my-image echo "bye"   # → "bye"  (CMD replaced)

# ENTRYPOINT only — fixed executable
FROM ubuntu:22.04
ENTRYPOINT ["echo"]

docker run my-image               # → ""  (nothing, no args)
docker run my-image "hello"      # → "hello"

# ENTRYPOINT + CMD — the most useful pattern
FROM ubuntu:22.04
ENTRYPOINT ["echo"]
CMD ["hello world"]

docker run my-image               # → "hello world"  (default)
docker run my-image "other text" # → "other text"  (CMD replaced)

The ENTRYPOINT + CMD combination is what you want for CLI tools packaged as containers: the tool is fixed, the arguments are defaults you can override without knowing anything about the image internals.

If you're following along but it's not fully clicking yet, that's fine — this is the combination that gets googled most often by people who've been using Docker for months. The 90% case is exec form in ENTRYPOINT with CMD as default arguments. The rest comes with practice.

Shell form vs exec form

Both instructions come in two flavors:

# Shell form — runs via /bin/sh -c
CMD echo "hello"
ENTRYPOINT echo "hello"

# Exec form — executes directly, no shell involved
CMD ["echo", "hello"]
ENTRYPOINT ["echo", "hello"]

Use exec form for ENTRYPOINT. Shell form runs your process as a child of /bin/sh, which has two annoying consequences: OS signals like SIGTERM (sent when stopping a container) don't reach your process because the shell intercepts them, and on minimal images without a shell the container simply won't start. With exec form, your process is PID 1 and receives signals directly.

HEALTHCHECK

This is the instruction no one adds until a container fails silently in production and it takes longer than it should to notice. After that, they add it to everything.

HEALTHCHECK tells Docker how to verify a container is functioning correctly. Docker runs the specified command on a schedule and updates the container's status: starting, healthy, or unhealthy.

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

CMD ["node", "index.js"]

The parameters:

--interval: how often the check runs (default: 30s)
--timeout: if the command takes longer than this, it's a failure (default: 30s)
--start-period: grace period at startup before failures start counting (default: 0s)
--retries: how many consecutive failures before marking as unhealthy (default: 3)

The check command should return 0 for healthy and 1 for unhealthy. The || exit 1 ensures that if curl fails — because the server isn't responding or returns an HTTP error — the check reports failure too.

docker ps

CONTAINER ID   IMAGE     STATUS
a1b2c3d4e5f6   my-app    Up 2 minutes (healthy)

That (healthy) in docker ps means the HEALTHCHECK is running and passing. Docker Compose and orchestrators use this status to know whether a container is ready to accept traffic, whether it needs to be restarted, and whether to consider a deploy successful.

If your image doesn't have curl — Alpine or distroless images — use wget or a small script in your app's runtime:

# With wget (Alpine)
HEALTHCHECK --interval=30s --timeout=5s \
  CMD wget -q --spider http://localhost:3000/health || exit 1

# With Node.js runtime
HEALTHCHECK --interval=30s --timeout=5s \
  CMD node -e "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))"

VOLUME and EXPOSE

Here's the part nobody documents well because it's genuinely a bit odd: EXPOSE doesn't expose anything and VOLUME doesn't mount anything. They're very formal comments that Docker decided to turn into instructions. The naming is optimistic.

EXPOSE

EXPOSE declares which port the container listens on. It does not open that port on the host. It does not make the container accessible from outside. It does nothing at runtime. It's executable documentation — it tells anyone reading the Dockerfile what port to publish, and tools like Docker Compose can discover it automatically.

EXPOSE 3000

To actually publish the port to the host, you need -p when running:

docker run -p 8080:3000 my-app
# Host port 8080 → container port 3000

EXPOSE without -p or ports: in Compose is invisible from the outside. Add it anyway — it's good documentation practice and some orchestrators use it for service discovery.

VOLUME

VOLUME declares a mount point inside the container. Docker will automatically create an anonymous volume for that path when the container starts, ensuring data persists even if the container is removed.

VOLUME ["/app/data", "/app/logs"]

What it doesn't do: it doesn't define where on the host the data lives (that's -v in docker run or volumes: in Compose), and it doesn't save you from having to specify the volume if you want control over it.

# Without specifying — Docker creates an anonymous volume
docker run my-app

# Named volume — recommended
docker run -v my-data:/app/data my-app

# Bind mount — host directory
docker run -v $(pwd)/data:/app/data my-app

The primary use of VOLUME in a Dockerfile is to document which paths contain data that shouldn't be lost. It also has a practical side effect: any content copied into that path before the VOLUME instruction is included in the initial volume state. Any COPY or RUN that writes to that path after VOLUME won't behave as expected.

⚠️ For this reason, put VOLUME near the end of the Dockerfile, after copying everything that needs to be there.

With ARG, ENV, ENTRYPOINT, CMD, HEALTHCHECK, VOLUME, and EXPOSE in your vocabulary, you have all the tools to write Dockerfiles that aren't just functional — they're configurable, predictable, and observable.

Next up is BuildKit: how to enable it, what real advantages it brings over the classic builder, and how to use it to handle build secrets and package caches without compromising security.

Never stop coding!

💡 Challenge: Open a Dockerfile from any project you have or from any open source repo. Check whether it uses shell form or exec form for ENTRYPOINT and CMD, whether it has a HEALTHCHECK, and whether environment variables are in ARG or ENV. Is there anything you'd change now?