DEV Community: Shakil Alam

The Audit Trail: Building a System That Remembers

Shakil Alam — Fri, 17 Apr 2026 16:33:26 +0000

Part 1 of 4 — Laravel Architecture Patterns for Production
~10 min read · Compliance · Model logging · Request tracing

A transaction record had been modified.

The amount was different from what the user had submitted. Support escalated it. The user denied changing anything. The developer who last touched the code was on leave. We looked at the database — the record had an updated_at from two days ago and a different value than expected. That was everything we had.

No who. No which fields. No context about what request caused it.

We had a working application. We did not have a system that remembered anything.

That was the incident that made us build this.

What you will build

A request ID generated in middleware that automatically appears in every log line for that request — no manual threading required
Field-level model diffs that capture what changed from and to, not just that a record was updated
Append-only log files segmented to stay fast at millions of records
A Gate hook that logs failed permission checks before they become incidents

What an audit trail actually needs to prove

Before writing code, it is worth being precise about what you are building — because "audit trail" means different things in different contexts, and the requirements determine the architecture.

If you need a queryable, database-backed audit log with a ready-made API, spatie/laravel-activitylog is the standard choice and it is well built. What follows is for when your requirements go further — append-only guarantees, field-level diffs, and audit records that are genuinely hard to tamper with.

In a compliance-heavy environment — fintech, healthcare, any regulated domain — an audit trail needs to answer four questions about any data change:

Who made the change (user ID, IP address, user agent)
What changed — not "the record was updated," but which fields, from what value to what
When it changed
Why it is trustworthy — the audit record itself cannot be quietly modified

Most implementations get the first three. The fourth is where they fail, and it is the one that matters most in an actual audit.

Here is the problem with a database audit table: your application code writes to it. That means your application code can also UPDATE it. A table that application code can modify is not an immutable record — it is a mutable history. An auditor who understands this will ask how you prevent tampering, and "we trust our own code" is not a satisfying answer.

This shapes the decision to use file-based logging. But first, there is a more foundational problem: correlation.

The request ID: one thread through every log

A model change does not happen in isolation. It happens during a request — a specific HTTP call from a specific user at a specific moment. Without connecting the model change to that request, you have timestamped facts with no story between them.

The solution is a request ID: a UUID generated at the start of every request and written into every log line that request produces.

Before building the middleware class, add the request and query channels to config/logging.php:

// config/logging.php
'channels' => [

    // ... your existing channels ...

    'request' => [
        'driver' => 'daily',
        'path'   => storage_path('logs/request.log'),
        'level'  => 'debug',
        'days'   => 90,        // Retain 90 days — adjust to your compliance requirement
    ],

    'query' => [
        'driver' => 'daily',
        'path'   => storage_path('logs/query.log'),
        'level'  => 'debug',
        'days'   => 30,
    ],

],

Then the middleware:

class RequestLogger
{
    public const HEADER_NAME          = 'X-Request-Id';
    public const REQUEST_ID_ATTRIBUTE = 'request_id';

    public function handle(Request $request, Closure $next): Response
    {
        $requestId = (string) Str::uuid();

        // Store in request attributes for internal access within the same request
        $request->attributes->set(self::REQUEST_ID_ATTRIBUTE, $requestId);
        // Also set as a header — downstream systems and the browser can read it
        $request->headers->set(self::HEADER_NAME, $requestId);

        // shareContext injects request_id into every Log:: call
        // for the rest of this request automatically — no manual threading required
        Log::shareContext(['request_id' => $requestId]);

        $startedAt = hrtime(true); // Monotonic clock — more accurate than microtime()
        $response  = $next($request);
        $response->headers->set(self::HEADER_NAME, $requestId);

        $this->logRequest($request, $response, $requestId, $startedAt);

        return $response;
    }

    private function logRequest(
        Request $request,
        Response $response,
        string $requestId,
        int $startedAt
    ): void {
        Log::channel('request')->info('request.completed', [
            'request_id'  => $requestId,
            'method'      => $request->method(),
            'path'        => $request->getPathInfo(),
            'status'      => $response->getStatusCode(),
            'duration_ms' => round((hrtime(true) - $startedAt) / 1_000_000, 2),
            'user_id'     => $request->user()?->getAuthIdentifier(),
            'ip'          => $request->ip(),
        ]);
    }
}

// Laravel 11 — bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\App\Http\Middleware\RequestLogger::class);
})

// Laravel 10 and earlier — app/Http/Kernel.php
protected $middleware = [
    // ...
    \App\Http\Middleware\RequestLogger::class,
];

Every log entry your application writes from this point on will now include the request ID automatically. Here is what a request log entry looks like in storage/logs/request.log:

{
  "message": "request.completed",
  "request_id": "9d4e2f1a-83bc-4a7c-b291-7e5f3d9a1c84",
  "method": "PATCH",
  "path": "/transactions/1101",
  "status": 200,
  "duration_ms": 43.2,
  "user_id": 42,
  "ip": "192.168.1.10",
  "level": "info",
  "level_name": "INFO"
}

And a model change log entry in storage/logs/activities/transactions/1100/transaction_1101.log:

{
  "event": "updated",
  "request_id": "9d4e2f1a-83bc-4a7c-b291-7e5f3d9a1c84",
  "time": "2024-03-15 14:32:07",
  "model_id": 1101,
  "changes": {
    "amount": { "old": "5000.00", "new": "500.00" }
  },
  "user_id": 42,
  "ip": "192.168.1.10",
  "user_agent": "Mozilla/5.0 ..."
}

The same request_id appears in both files. That is the correlation. When a support ticket says "something changed on Transaction 1101," you grep that ID across both logs and have the complete picture immediately.

Why Log::shareContext() instead of passing the ID manually everywhere? shareContext() injects the given data into every Log:: call for the rest of the request lifecycle automatically. You do not thread the request ID through your services, model observers, or Gate hooks. Whatever you log, the request ID is already there.

Why UUID instead of a random integer? A six-digit random int has a real collision probability under concurrent load. A UUID is 128 bits of randomness — collision is not a realistic concern. The ID also goes into the response header (X-Request-Id), so a user who raises a support ticket can include it and you find the exact request in seconds.

Why a single structured entry after the response rather than separate request-in and response-out entries? One entry per request gives you the complete picture — method, path, status code, duration — in one line without cross-referencing. The hrtime(true) monotonic clock is more accurate for duration measurement than microtime() because it is not affected by system clock adjustments.

A note on X-Forwarded-For: When your application sits behind a load balancer, request()->ip() returns the proxy's IP, not the user's. The TrustProxies middleware resolves this — once configured, request()->ip() returns the real client IP. Pass it to external API calls so downstream system logs also record the real user, not your server's address.

Slow queries: while you are here, add this

This is a separate concern from the audit trail — but since you are already setting up logging infrastructure, it costs almost nothing to add and consistently pays off the first time a performance problem hits production.

The idea: log slow queries with severity levels matched to how serious the slowness actually is.

// AppServiceProvider.php
// Scope this to non-production environments or behind a config flag
// in high-traffic systems — DB::listen fires on every query.
if (config('app.debug') || config('logging.query_listener')) {
    DB::listen(function ($query) {
        $time = $query->time;

        match(true) {
            $time > 10000 => Log::channel('query')->critical("Extremely slow ({$time}ms)"),
            $time > 1000  => Log::channel('query')->error("Very slow ({$time}ms)"),
            $time > 100   => Log::channel('query')->warning("Slow ({$time}ms)"),
            default       => null, // Fast queries add noise without value
        };
    });
}

Why map duration to log level? Because log levels mean something — or they should. If everything is info, nothing stands out. A 12-second query logged as critical will trigger any alert rule that fires on critical log entries without writing any additional monitoring code.

Why the config gate? DB::listen fires on every single query. In a high-traffic production environment, the overhead is real. Gate it behind app.debug or a dedicated config flag so you control when it runs.

The 100ms warning threshold is the fastest way to surface missing indexes and N+1 problems. You see the warning in the logs, you add the index, the warning stops. No user ever had to complain.

That said — this is optional. If you add nothing else from this section, the audit trail still works. The query listener is a low-cost addition that earns its place, not a requirement.

The model change logger

With a request ID threading through the system, model-level changes become meaningful entries in a traceable story rather than isolated database facts.

The implementation is a trait on any Eloquent model that needs auditing:

trait ModelChangeLogger
{
    public static function bootModelChangeLogger(): void
    {
        static::updating(function ($model) {
            $changed = array_diff_assoc(
                $model->getAttributes(),
                $model->getOriginal()
            );

            // updated_at is present in every update. It is never interesting.
            unset($changed['updated_at']);

            if (empty($changed)) {
                return;
            }

            // Build a field-level diff — not just the new values,
            // but what each field changed *from*
            $diff = [];
            foreach ($changed as $key => $newValue) {
                $diff[$key] = [
                    'old' => $model->getOriginal($key) ?? 'N/A',
                    'new' => $newValue,
                ];
            }

            $model->logChanges($diff, 'updated');
        });

        static::created(function ($model) {
            $model->logChanges($model->getAttributes(), 'created');
        });

        static::deleting(function ($model) {
            // Capture the full state before deletion — after deletion,
            // getAttributes() returns nothing useful
            $model->logChanges($model->getAttributes(), 'deleted');
        });
    }

    protected function prepareLogData(array $changes, string $event): array
    {
        // Mask sensitive fields before writing — log that they changed,
        // not what they changed to
        foreach ($this->maskedAttributes ?? [] as $attr) {
            if (isset($changes[$attr])) {
                $changes[$attr] = ['old' => '[REDACTED]', 'new' => '[REDACTED]'];
            }
        }

        return [
            'event'      => $event,
            'request_id' => request()->attributes->get(RequestLogger::REQUEST_ID_ATTRIBUTE, 'N/A'),
            'time'       => now()->toDateTimeString(),
            'model_id'   => $this->getKey(),
            'changes'    => $changes,
            'user_id'    => auth()->id(),
            'ip'         => request()->ip(),
            'user_agent' => request()->userAgent(),
        ];
    }

    // Override in each model to list fields that should never appear in plain text
    protected array $maskedAttributes = [];
}

A note on console context: When ModelChangeLogger runs inside a queued job or a scheduled command rather than an HTTP request, request()->attributes->get(REQUEST_ID_ATTRIBUTE) returns 'N/A' — that is the intentional fallback, not a bug. If you want correlation in background jobs, generate a job-level UUID in the job constructor and inject it via Log::shareContext() at the start of handle(), the same way RequestLogger does for HTTP requests.

Why getOriginal() rather than just the new values? Because "the amount field is now 500" is half the story. "The amount field changed from 5000 to 500" is evidence. In a dispute, the diff proves the change happened — not just the current state.

Why capture deleting before the delete, not after?

Common mistake: Using static::deleted instead of static::deleting for the deletion hook. deleted fires after the row is gone — getAttributes() returns nothing. Always use deleting.

deleting fires before the row is removed — the full record is still in memory. deleted fires after, and getAttributes() returns an empty array at that point.

File-based logs and the folder segmentation problem

Here is the decision that shapes the rest of the logging architecture: where do the log entries live?

The database option is tempting — it is queryable, indexable, and fits naturally into a Laravel application. The problem: any table your application can write to, your application can also modify. An UPDATE audit_logs is valid SQL. In a regulated environment, mutable audit records are a compliance liability.

Append-only log files are harder to tamper with. FILE_APPEND at the OS level means every write goes to the end — there is no update operation, only add. Combined with filesystem permissions where the web user can write but not delete, you have logs that are genuinely difficult to alter.

protected function logChanges(array $changes, string $event): void
{
    $logPath = $this->buildLogPath();

    file_put_contents(
        $logPath,
        json_encode($this->prepareLogData($changes, $event)) . PHP_EOL,
        FILE_APPEND | LOCK_EX  // LOCK_EX prevents concurrent writes corrupting the file
    );
}

Common mistake: Using FILE_APPEND alone. On a busy system where multiple requests modify records simultaneously, two processes can interleave their writes and corrupt a log entry. LOCK_EX acquires an exclusive lock — one write completes fully before the next begins. Both flags are required.

The folder structure problem: if you store each record's log in a folder named after the table, you eventually have transactions/ containing one file per transaction. A million transactions means a million files in one directory. Most filesystems handle this technically, but ls, backup tools, and directory enumeration operations become painfully slow.

The solution is segmentation — group records into subdirectories by ID range:

protected function buildLogPath(): string
{
    $id      = $this->getKey();
    $table   = $this->getTable();

    // Segment folder: floor to the nearest 100
    // IDs 1–99 → folder "0", IDs 100–199 → folder "100", IDs 1100–1199 → folder "1100"
    $segment = (int) (floor($id / 100) * 100);

    $folder = storage_path("logs/activities/{$table}/{$segment}");

    if (!is_dir($folder)) {
        mkdir($folder, 0755, true);
    }

    $filename = strtolower(class_basename($this)) . "_{$id}.log";

    return "{$folder}/{$filename}";
}

The result on disk:

storage/logs/activities/
    transactions/
        0/
            transaction_1.log
            transaction_42.log
        1100/
            transaction_1101.log
            transaction_1102.log
        1200/
            transaction_1200.log
    users/
        0/
            user_1.log

Each folder contains at most 100 files. Finding a specific record's history means knowing its ID — which you always do — and reading one file. The structure scales to any number of records without any folder becoming unwieldy.

Masking sensitive fields

An audit trail that contains plaintext national ID numbers or passwords creates its own compliance problem. In many jurisdictions, a log file with unredacted PII is treated like any other PII store — subject to retention limits, access controls, and deletion rights.

The approach here records that the field changed without recording what it changed to. An auditor can see that national_id was modified on Transaction 1101 at 14:32 by User 42 — which satisfies the audit requirement — without the log file holding the actual values.

Override $maskedAttributes on any model that stores sensitive data:

class Transaction extends Model
{
    use ModelChangeLogger;

    protected array $maskedAttributes = [
        'national_id',
        'card_number',
    ];
}

Where RBAC fits into this picture

Access control and audit trails are related problems. If you are logging who changed records, you should also log who tried to do something they were not allowed to.

Laravel's Gate provides a hook for exactly this:

Gate::after(function (User $user, string $ability, bool $result) {
    if (!$result) {
        // request_id is automatically included via Log::shareContext()
        // set in RequestLogger — no need to fetch it manually here
        Log::channel('request')->warning('Authorization denied', [
            'user_id' => $user->id,
            'ability' => $ability,
            'ip'      => request()->ip(),
        ]);
    }
});

Why log failures specifically? A successful authorization attempt is normal operation. A failed attempt is a signal — a user may be probing endpoints they should not have access to, or a compromised account may be attempting privilege escalation. The pattern across multiple failed attempts becomes early warning you would not have without this hook.

One design principle worth stating: design permissions around abilities, not role names. $user->can('transaction.approve') expresses what the user can do, regardless of what role label they carry. $user->role === 'admin' breaks the moment "admin" means different things in different contexts — and in growing systems, it always eventually does.

What you now have

Register RequestLogger as global middleware. Add ModelChangeLogger to any Eloquent model. Register the Gate::after hook.

Now: every request carries an ID. Every model change records who made it, which field changed from what value to what, when, and which request caused it. Failed permission checks are logged. Every log line across your stack shares a common correlation ID.

When a support ticket arrives saying "something changed on Transaction 1101," you open storage/logs/activities/transactions/1100/transaction_1101.log. You see the exact diff, the user who made it, the request ID. You grep that request ID in your request logs. You have the complete picture in under a minute.

That is the difference between an application that works and one that remembers.

The key insight from this article: A database audit table is mutable — your application code can UPDATE it. Append-only log files with a request ID threaded through every entry give you tamper-resistant, correlated records that answer who, what, and why in one grep.

Before you ship — checklist

[ ] RequestLogger registered as global middleware in bootstrap/app.php
[ ] ModelChangeLogger trait added to every model that handles sensitive or auditable data
[ ] $maskedAttributes defined on models that store PII (passwords, national IDs, card numbers)
[ ] storage/logs/activities/ is writable by the web user, not deletable
[ ] DB::listen is gated behind a config flag or app.debug — not running unconditionally in production
[ ] Gate::after hook registered in AuthServiceProvider
[ ] A grep for a known request ID returns results across both the request log and model change logs

Next: Part 2 — Queue Architecture: Designing Background Work That Holds Up

Laravel Architecture Patterns for Production

Shakil Alam — Fri, 17 Apr 2026 16:28:52 +0000

Most Laravel applications work. Routes respond, data gets saved, users can log in. The framework handles it.

Then the hard questions arrive. Can you prove that transaction wasn't tampered with? Or: what happens when a bulk operation dispatches 5,000 jobs overnight? Or: what happens to our users when that third-party API goes down?

These are the questions that separate a Laravel application that works from one that holds up.

This series is built from real production code — written after those questions were asked, after something went wrong, after a requirement changed in a way the original architecture couldn't handle. Every pattern came from a real system under real pressure: fintech, regulated environments, places where "it works" is not a sufficient answer.

Who this is for: You have shipped Laravel to production. You know the framework. Now you are being asked to make the system serious — audit-ready, reliable under load, and defensible under scrutiny. You want the reasoning behind the patterns so you can adapt them, not just the code to copy.

Requirements: PHP 8.0+ and Laravel 9+ for all four parts. Part 4 uses Illuminate\Support\Facades\Context, which requires Laravel 11 — a compatible fallback for earlier versions is shown in that article.

On scope: These patterns came from specific production environments and reflect specific tradeoffs. They are documented decisions, not universal prescriptions. Each article names the tradeoffs and labels the common mistakes so you can make an informed choice for your own context.

The Four Parts

Part 1 — The Audit Trail: Building a System That Remembers

~10 min read · Compliance · Model logging · Request tracing

A request ID generated in middleware that automatically appears in every log line for that request. Field-level model diffs that capture what changed from what value to what — not just that a record was updated. Append-only log files segmented to stay fast at scale. A Gate hook that logs failed permission checks before they become incidents.

A database audit table is mutable. Append-only files are not. That one sentence shapes the entire architecture.

Part 2 — Queue Architecture: Designing Background Work That Holds Up

~9 min read · Queue design · Job architecture · Background processing

Why passing an Eloquent model to a job constructor is the wrong call, and what to pass instead. How to design a queue topology before you are forced to by a problem. Retry strategies matched to transient, rate-limited, and permanent failures. File operations written to survive a crash mid-write.

A password reset email stuck behind a video compression job is not a queue problem. It is a topology problem.

Part 3 — Secure File Uploads: Seven Checks and Why Each One Exists

~9 min read · Security · Middleware · File handling

A middleware that validates seven independent properties of every uploaded file, each one named and explained. Server-side MIME detection using finfo — not the browser's claim. A unique name strategy that removes user-controlled strings from filesystem paths entirely. A storage pattern where no uploaded file is ever directly reachable via HTTP.

getClientMimeType() returns whatever the browser sent. finfo reads the actual bytes. Only one of those is a security check.

Part 4 — External API Reliability: When Their System Goes Down

~9 min read · Integration architecture · Resilience · Fault tolerance

A trait that makes the fallback decision — fail loud or fail silent — explicit in the model, not buried in a catch block. A recovery path for operations that completed externally but failed locally. The idempotency question, and why it matters when the database write fails after the external API already accepted the request.

The 2am outage will still happen. The question is whether your system has a designed response or an improvised one.

Each article stands on its own. But if you are reading from the start, Part 1 establishes a request ID that runs as a thread through every subsequent part.

How I Reduced Video Storage by 30GB/Day Using FFmpeg and Laravel

Shakil Alam — Tue, 07 Apr 2026 16:09:11 +0000

Most teams don't realize how expensive "just 30 seconds of video" can become — until it silently turns into terabytes of storage and a massive monthly bill.

That's exactly what happened to us.

We were storing millions of short verification clips, each only ~30 seconds long — but together, they were costing us hundreds of GBs every month.

Instead of throwing money at storage, we decided to fix the root problem.

The result?
👉 20–30 GB saved per day
👉 60% average compression
👉 Zero impact on review quality

At my company, we run a video-based verification flow — users record short clips (typically 30 seconds) that get reviewed by our team. Simple enough. But over time, those clips add up fast.

We had millions of recorded videos in storage with a retention requirement of 2–4 years. The storage bill kept climbing. The turning point came when I actually measured what we were storing — and realized we were saving far more data than we needed to.

This is the story of how I built a pipeline that now compresses 2,000+ videos per day and saves 20–30 GB of storage daily — without touching a single live file.

Real Numbers from Production

Before going into the how, here's what one day's run looks like on our compression dashboard:

Metric	Value
Videos processed	2,203
Total space saved	15.66 GB
Average compression ratio	62.1%
Best compression recorded	99.92%

An average reduction of 62% in file size. Some clips (usually silent or nearly-static ones) compress all the way to 99.9%. Even on a typical day, we're saving 15+ GB from a single cron run.

The Problem: Over-Engineered for the Wrong Use Case

Our original recording setup used browser defaults — high resolution, high framerate, stereo audio at 48kHz. Reasonable general-purpose settings, but completely overkill for a 30-second face verification clip.

When the backlog started growing into the millions of files, the cost became impossible to ignore. But before writing a single line of compression code, I needed to understand why the files were so large — and fix the source before compressing the backlog.

Step 1: Research, Experiment, Validate

I didn't just pick lower settings and ship them. I researched codec behavior, tested different bitrate and quality combinations, and — critically — validated with real recordings before touching user traffic.

The validation approach: Our verifiers (the people who review verification videos) also record their own video profiles. This was the perfect test population — small, controlled, and internal. I rolled out the new recording constraints to verifier accounts first and asked them to record 10-second clips, much longer than a typical verification video.

Why 10 seconds? Because problems with codec settings, device compatibility, or audio quality tend to hide in short clips but surface in longer ones. Buffer issues, audio sync drift, encoding artifacts under motion — these all become visible when you push the duration.

Once the verifier videos came back clean across a range of devices (Chrome on Android, Chrome on desktop, Safari on iOS), I had confidence the settings were correct. Only then did I roll them out to user-facing recording.

Step 2: Optimize Video Recording at the Source

Understanding Browser Codec Support (VP8 vs VP9)

Modern browsers support two primary video codecs for MediaRecorder:

VP8 — the older WebM codec. Widely supported across all browsers and platforms, including older Android devices. Less efficient compression than VP9 but extremely reliable.

VP9 — Google's newer codec. Significantly better compression at the same quality level, especially for low-motion content like talking heads. Supported in Chrome, Firefox, and most modern browsers, but not always available on older devices or in certain Safari contexts.

Why fallback matters: If you specify video/webm;codecs=vp9,opus and the browser or device doesn't support VP9, MediaRecorder will either throw an error or silently produce a broken file. A hardcoded codec choice that works on your test device will fail on some percentage of real users' devices. You need to probe support at runtime:

const mimeTypes = [
  'video/webm;codecs=vp9,opus',   // Best: VP9 video + Opus audio
  'video/webm;codecs=vp8,opus',   // Good: VP8 video + Opus audio
  'video/webm'                     // Fallback: browser chooses
];

const mimeType = mimeTypes.find(type => MediaRecorder.isTypeSupported(type)) || '';

MediaRecorder.isTypeSupported() checks at runtime whether the current browser/device combination actually supports a given MIME type. The list is ordered by preference — VP9 first, VP8 second, browser default last. Whatever the device supports, it gets the best available option.

The actual recording constraints

const constraints = {
  video: {
    width: { ideal: 640 },
    height: { ideal: 480 },
    frameRate: { ideal: 24 }
  },
  audio: {
    sampleRate: 16000,
    channelCount: 1,        // mono
    echoCancellation: true,
    noiseSuppression: true
  }
};

const mediaRecorder = new MediaRecorder(stream, {
  mimeType,
  videoBitsPerSecond: 1_000_000,    // 1 Mbps cap
  audioBitsPerSecond: 64_000         // 64 Kbps cap
});

Why each decision:

640×480 at 24fps — Sufficient to clearly identify a face. 30fps and 1080p are for content you'll watch repeatedly; a verification clip gets reviewed once.
16kHz mono audio — Voice intelligibility tops out around 8kHz. 16kHz captures speech clearly with half the data of 44.1kHz stereo. The verifier needs to hear what someone says, not enjoy high-fidelity audio.
1 Mbps video / 64 Kbps audio — A cap at the recorder level. Without this, VP8 in particular can spike well above reasonable bitrates on some devices.
echoCancellation + noiseSuppression — These reduce audio variance, which compresses better downstream. Noisy or echoey audio encodes less efficiently.

Step 3: Compress the Backlog

Fixing the source stopped the problem from growing. But millions of old files still existed at the original large sizes. I built a three-layer Laravel pipeline to work through them.

Layer 1 — Artisan Command

php artisan media:compress-videos --chunk=200 --dry-run

# or target a single video for testing:
php artisan media:compress-videos --id=202423

The command queries all records with a video/% MIME type, chunks them into batches of 200, and dispatches a queued job per video. The --dry-run flag lets you see what would be processed without doing anything — useful before running on production for the first time.

Layer 2 — Queued Job

class CompressMediaVideo implements ShouldQueue
{
    public int $tries = 3;
    public int $timeout = 120;

    public function handle(VideoCompressorService $compressor): void
    {
        $media = Media::findOrFail($this->mediaId);

        if (!str_starts_with($media->mime_type, 'video/')) {
            return; // skip safely
        }

        $compressor->compress($media);
    }
}

One job per video. If a job fails, it retries independently without affecting the others. The compression run can take months on a backlog of millions — having individual, retryable jobs means a server restart or a bad file doesn't set you back to zero.

Layer 3 — Deep Dive into FFmpeg Compression Strategy

This is where the actual compression happens. Some context on how it works:

What FFmpeg is doing: It reads the original WebM file (usually H.264 video + Opus audio, recorded by Chrome), re-encodes the video track using VP9, re-encodes the audio using Opus at a lower bitrate, and writes a new WebM container.

Why VP9 for compression? VP9 uses much more sophisticated algorithms than H.264 — it's better at identifying redundant information across frames and removing it. For a mostly-static scene like a person talking against a wall, VP9 can throw away enormous amounts of data while keeping the image perfectly clear to a human reviewer.

What CRF means: CRF (Constant Rate Factor) is quality-controlled encoding. Instead of targeting a specific bitrate, you specify a quality level and FFmpeg decides how many bits are needed to achieve it. Lower CRF = higher quality = larger file. Higher CRF = more compression = smaller file.

For VP9, CRF 33 is roughly "good quality." CRF 35 is "slightly aggressive." CRF 40+ starts to look visibly degraded. I chose CRF 35 because:

It's a face verification clip, not a film
The reviewer needs to see the face clearly, not count pores
Our production data confirms it works — the 62.1% average compression ratio came from CRF 35

$command = [
    'ffmpeg', '-i', $inputPath,
    '-c:v', 'libvpx-vp9',
    '-crf', '35',
    '-b:v', '0',           // Required for CRF mode in VP9
    '-c:a', 'libopus',
    '-b:a', '64k',
    '-y', $tempPath
];

Note: -b:v 0 is required when using CRF mode with libvpx-vp9. Without it, VP9 defaults to a target bitrate mode and ignores the CRF value.

Safe Processing with Atomic File Replacement

$exitCode = $process->run();

if ($exitCode !== 0) {
    @unlink($tempPath);
    // Log and store error output for debugging
    $media->update(['compressed_meta' => ['error' => $process->getErrorOutput()]]);
    return;
}

// Only replace the original after successful compression
rename($tempPath, $inputPath);

FFmpeg writes to a .tmp file first. If encoding fails for any reason — corrupt input, disk full, process killed — the original file is untouched. The rename() only happens after a confirmed successful exit code. In a pipeline processing millions of files, this matters.

The service also skips files that would grow: if the compressed output is larger than the original (which happens with already-optimized or very short files), saved_bytes is recorded as 0 and the original is kept. The dashboard's -130.33% low value represents exactly this case — a tiny file that got larger under re-encoding.

Step 4: Storage Lifecycle Management (Trash + Cleanup Strategy)

When a verification video is rejected and the user records a new one, we don't immediately delete the old clip. It gets moved to a trash/ directory. A weekly cron job permanently removes everything older than 7 days in trash.

This gives the ops team a recovery window without keeping rejected videos indefinitely. It also keeps the compression pipeline clean — trash videos are excluded from the compression queue since they're headed for deletion anyway.

Results

One day's run (March 11, 2026):

2,203 videos compressed
15.66 GB saved
62.1% average compression ratio

Projected at scale:

At ~20 GB/day average: 600 GB/month, 7+ TB/year
The backlog has millions of videos — this pipeline will run for months
New uploads are already smaller thanks to the recording constraint changes

Key Takeaways

Validate on internal users first. Rolling out recording changes to verifier accounts before users meant any issues would be caught internally. Testing with 30-second clips specifically surfaces problems that short clips hide.
Probe codec support at runtime. Never hardcode a MIME type. MediaRecorder.isTypeSupported() is a one-liner that ensures every device gets the best encoding it can handle.
CRF over bitrate caps. A fixed bitrate wastes bits on simple scenes and starves complex ones. CRF adapts to content — simple talking-head frames get very small, complex frames get what they need.
-b:v 0 is not optional for VP9 CRF. This trips up a lot of people. VP9 in FFmpeg defaults to bitrate mode; CRF only activates when you explicitly set -b:v 0.
Atomic writes protect your data. In bulk processing, things fail. Write to temp, verify success, then rename. Never write directly to the live path.
Queue per file, not per batch. Individual queued jobs make the pipeline restartable, observable, and fault-tolerant. A bad file fails in isolation; everything else keeps running.

I write about backend engineering and fintech systems at blog.shakiltech.com. If this was useful, the next post covers the Laravel queue architecture behind this pipeline.

Laravel Fast2SMS v2.0.0 — WhatsApp Support, Notification Channels & a Smarter DX

Shakil Alam — Sun, 29 Mar 2026 05:07:09 +0000

When I shipped v1, the goal was simple: send SMS to Indian phone numbers from Laravel without wrestling raw API arrays. v2.0.0 takes that same idea much further.

The headline is WhatsApp Business API support — text, images, documents, locations, templates, reactions, stickers, and interactive messages, all through the same familiar Fast2sms facade. Beyond that, v2 brings drop-in Laravel Notification Channels, a typed exception hierarchy, expressive testing utilities, and cost-saving guards that protect your wallet in production.

⚠️ This is a major release with breaking changes. See the Upgrade Guide before updating.

Let me walk you through what matters.

💬 WhatsApp Business API

This is the big one. Starting in v2.0.0, the package supports the Fast2SMS WhatsApp Business API through Fast2sms::whatsapp().

Send a plain text message:

use Shakil\Fast2sms\Facades\Fast2sms;

Fast2sms::whatsapp()
    ->to('9999999999')
    ->text('Your order has been shipped and is on its way!')
    ->send();

Send an image with a caption:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->image('https://yourapp.com/invoice.png', caption: 'Your invoice for order #1042')
    ->send();

Send a document:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->document('https://yourapp.com/receipt.pdf', filename: 'receipt.pdf')
    ->send();

Send a location:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->location(lat: 28.6139, lng: 77.2090, name: 'New Delhi')
    ->send();

Send a registered template:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->template(id: 'YOUR_TEMPLATE_ID', variables: ['John', 'Order #1042'])
    ->send();

React to a message, send a sticker, or build interactive button flows — the full WhatsApp API surface is available through the same fluent chain.

🔔 Laravel Notification Channels

v2 ships two drop-in notification channels: SmsChannel and WhatsAppChannel. Your existing notification classes work exactly the way you'd expect.

use Shakil\Fast2sms\Channels\SmsChannel;
use Shakil\Fast2sms\Channels\WhatsAppChannel;
use Shakil\Fast2sms\Messages\SmsMessage;
use Shakil\Fast2sms\Messages\WhatsAppMessage;

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        return [SmsChannel::class, WhatsAppChannel::class];
    }

    public function toFast2sms($notifiable): SmsMessage
    {
        return SmsMessage::create()
            ->otp('Your OTP is 482910. Valid for 10 minutes.');
    }

    public function toWhatsApp($notifiable): WhatsAppMessage
    {
        return WhatsAppMessage::create()
            ->text('Your order has been shipped!');
    }
}

Add the routing methods to your User model and you're done:

public function routeNotificationForFast2sms(): string
{
    return $this->phone_number;
}

public function routeNotificationForWhatsapp(): string
{
    return $this->phone_number;
}

No facade, no manual number passing. Just idiomatic Laravel.

🧱 Typed Exception Hierarchy

In v1, every API failure threw a single Fast2smsException. In v2 you can catch exactly what you need:

use Shakil\Fast2sms\Exceptions\AuthenticationException;
use Shakil\Fast2sms\Exceptions\RateLimitException;
use Shakil\Fast2sms\Exceptions\InsufficientBalanceException;
use Shakil\Fast2sms\Exceptions\NetworkException;

try {
    Fast2sms::otp('9999999999', '845621');
} catch (InsufficientBalanceException $e) {
    // Notify your team — wallet is empty
} catch (RateLimitException $e) {
    // Back off and retry
} catch (AuthenticationException $e) {
    // API key is wrong or expired
} catch (NetworkException $e) {
    // Fast2SMS was unreachable
}

The full list of typed exceptions is in the changelog.

🧪 Rich Fake Assertions for Testing

v2 ships 16 assertion methods on Fast2smsFake so your feature tests are expressive and readable — no more inspecting raw recorded calls.

Fast2sms::fake();

// ... trigger your code ...

Fast2sms::assertSmsSentTo('9999999999');

Fast2sms::assertSmsSentTo('9999999999', fn ($sms) =>
    str_contains($sms->message, '482910')
);

Fast2sms::assertWhatsAppSentTo('9999999999');

Fast2sms::assertNothingSent();

// Clean up for tests that need real sending
Fast2sms::stopFaking();

💡 Fluent Message Builders with Credit Helpers

SmsMessage and WhatsAppMessage are first-class objects with named constructors and chainable setters. SmsMessage also ships with credit helpers so you can estimate cost before you send:

use Shakil\Fast2sms\Messages\SmsMessage;

$message = SmsMessage::create()
    ->withContent('Your appointment is confirmed for tomorrow at 10am.')
    ->withRoute(SmsRoute::QUICK);

$message->charCount();       // character count
$message->isUnicode();       // true if Unicode encoding is needed
$message->creditCount();     // SMS credits this will consume
$message->exceedsOneSms();   // true if longer than one SMS

No more guessing whether a long message costs 1 credit or 3.

🛡️ Cost-Saving Guards

v2 introduces a set of opt-in guards that protect your wallet in production. All are off by default — enable only what your use case needs in config/fast2sms.php:

Guard	What it does
Recipient deduplication	Strips duplicate numbers before every send
Invalid recipient stripping	Validates numbers and logs warnings instead of failing hard
Idempotency guard	Blocks the same message being sent twice within a TTL window
Rate throttle	Sliding-window per-minute cap via Laravel cache
Balance gate	Checks your wallet before sending; fires `LowBalanceDetected` when low
Batch splitting	Splits large recipient lists into chunks automatically

⚙️ New Artisan Commands

# List every event the package fires, with descriptions
php artisan fast2sms:events

# Generate an IDE helper file for full autocompletion
php artisan fast2sms:ide-helper

Run fast2sms:ide-helper once after install and get full autocompletion on every facade method in PhpStorm or VS Code.

🚀 Getting Started

Requirements: PHP ^8.3 (8.4 and 8.5 also tested), Laravel 11, 12, or 13.

composer require itxshakil/laravel-fast2sms

php artisan vendor:publish --tag=fast2sms-config

FAST2SMS_API_KEY="your-api-key"
FAST2SMS_DEFAULT_SENDER_ID="FSTSMS"
FAST2SMS_DEFAULT_ROUTE="dlt"

Upgrading from v1

The public sending API — Fast2sms::quick(), ::dlt(), ::otp(), and now ::viaWhatsApp() — is completely unchanged. Most v1 code will work without modification.

The breaking changes are in internals: exception types, DTOs, and return type hints. The full step-by-step migration is in UPGRADING.md.

Git Explained Simply — For People Who Have No Idea What It Is

Shakil Alam — Sun, 15 Mar 2026 08:44:59 +0000

You've seen the word Git everywhere.

Job listings. GitHub. Tutorials that just assume you already know what it means. Nobody ever stopped to explain it from scratch.

This post is that explanation.

No jargon. No assumed knowledge. By the end you'll know what Git is, why it exists, and how to make your first commit — in about 15 minutes.

What is Git?

Git is a tool that saves every version of your code — not just the latest one.

Here's a simple way to think about it:

Imagine you're writing an essay in Word. Every time you hit Save, the old version disappears. You only ever have the latest copy. Delete a paragraph and save — that paragraph is gone forever.

Now imagine you could hit a special kind of Save that:

Keeps every previous version, forever
Lets you go back to any version at any time
Lets you add a note explaining what you changed and why
Lets you try something risky without touching your working version

That's Git. For code instead of essays.

Why does this matter?

Without Git, developers end up doing things like:

Saving files as project_final.js, project_final_v2.js, project_ACTUAL_FINAL.js
Deleting something, realising they needed it, having no way to get it back
Two people editing the same file and overwriting each other's work
Being afraid to make changes because they might break something

Git solves all of these. That's why every professional developer uses it.

Git vs GitHub — they are not the same thing

This trips up almost everyone at first.

Git is a tool that runs on your computer. It tracks your code history. It's free, open source, and works completely offline.

GitHub is a website. It stores your Git history online, lets you share your code, and makes it easy to collaborate with other developers. Think of it like Google Drive, but built specifically for Git.

You can use Git without GitHub. But most developers use both together — Git on their machine to track changes, GitHub online to back up and share.

Five words you'll hear constantly

Before we touch any commands, here are the five terms that come up in almost every Git conversation. Read them once — you don't need to memorise them, just have a rough idea so they don't throw you when you see them.

Repository (repo)
A repository is just a project folder that Git is watching. That's it. When a developer says "clone the repo" or "push to the repo" they mean the project. Your my-first-project folder? Once you run git init inside it, that's a repository.

Commit
A commit is a snapshot — a permanent record of exactly what your code looked like at a specific moment. Every commit has a short message you write yourself, like "Add login page" or "Fix broken checkout button". Think of it as pressing Save, but instead of overwriting the last save, Git keeps every single one and lines them up in order. You can go back to any of them at any time.

Branch
Imagine you're writing a book and you want to try a completely different ending — but you don't want to delete the original. You'd make a copy, experiment on the copy, and if it works, swap it in. If it doesn't, throw it away.

That's a branch. It's a separate version of your project where you can make changes freely, without touching anything that's working. When you're happy with the changes, you merge the branch back in. If you hate it, you just delete the branch — your original code is completely untouched.

This is one of the most powerful things Git does, and you'll use it constantly once you get the hang of it.

Push
When you commit, the snapshot is saved on your computer only. Push is how you send those commits up to GitHub so they're backed up online and others can see them.

Computer → GitHub = Push

Pull
The opposite of push. If someone else on your team made changes and pushed them to GitHub, pull is how you get those changes down onto your computer.

GitHub → Computer = Pull

That's all five. After you've used Git for a day or two, these words will feel completely natural.

Your first 15 minutes with Git

Let's actually do it rather than just talk about it.

Step 1 — Install Git

Go to git-scm.com and download Git for your system. Install with the default options.

Open your terminal and check it worked:

git --version

If you see something like git version 2.43.0 — you're set.

Step 2 — Tell Git who you are

Git labels every commit with your name and email. Set them once:

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

This only needs doing once per computer.

Step 3 — Create your first repository

mkdir my-first-project
cd my-first-project
git init

git init tells Git: start watching this folder. That's it — you now have a Git repository.

Step 4 — Add a file and make your first commit

Create a simple file:

echo "Hello, Git!" > hello.txt

Saving a file in Git is a two-step process:

Stage it — tell Git you want to include this file in the next snapshot:

git add hello.txt

Commit it — take the actual snapshot, with a message:

git commit -m "Add hello.txt"

You just made your first commit. Git has permanently recorded this moment.

Step 5 — Make a change and watch Git track it

Edit hello.txt — change the text to anything, save the file. Now run:

git status

Git tells you the file has changed. To see exactly what changed, line by line:

git diff

Lines you removed show in red. Lines you added show in green. Git caught everything automatically.

Commit the change:

git add hello.txt
git commit -m "Update the greeting"

Step 6 — Look at your history

git log --oneline

Both commits are listed. This list grows with every commit you ever make. It never gets deleted. That's your permanent history.

Why two steps? (The staging question everyone asks)

New developers always wonder why you can't just commit directly without staging first.

The staging step (git add) exists so you can choose exactly what goes into a commit. You might have changed five files but only want to save two of them right now. Staging gives you that precision.

It feels awkward the first few times. After a week it becomes automatic.

The one habit that makes all the difference

Commit small. Commit often.

Every time you finish one thing — not everything, just one small thing — make a commit. Every time the code is in a working state you want to remember, make a commit.

❌ Bad commit message	✅ Good commit message
`stuff`	`Add email validation to the signup form`
`fix`	`Fix broken checkout button on mobile`
`update`	`Update user profile to allow avatar uploads`

The message is not for Git. It's for you, six months from now, trying to figure out what you were thinking.

Most teams follow a format called Conventional Commits that makes messages consistent across the whole team. It's the single most impactful habit to build early: Commit Like a Pro: A Beginner's Guide to Conventional Commits

What to learn next

Set up Git properly for real projects
SSH keys, useful config, connecting to GitHub — the setup that makes Git work smoothly day to day:
Practical Git & GitHub Setup for Real-World Projects

git switch vs git checkout
You'll see both in tutorials. They do similar things — here's the difference:
Git Checkout vs Git Switch

How to recover anything you thought you deleted
Once you've used Git for a bit, this is the one that makes you feel invincible:
Git Reflog Explained: Recover Deleted Commits & Lost Work

Find exactly which commit broke something
Git has a built-in tool that searches your entire history automatically:
Git as Your Safety Net: The Confidence to Work Fearlessly

The full Git Mastery Series

When you're ready to go beyond the basics, this series takes you from how Git actually thinks to using it as your permanent safety net:

How Git Actually Thinks — the mental model that changes everything
Committing with Intention — writing commits that mean something
Branching Without Fear — working in parallel without breaking things
Collaboration That Doesn't Create Chaos — working with a team
Git as Your Safety Net — recovering from anything

If you want everything in one place — checklists, 80+ commands, hook templates, and a recovery playbook for when things go wrong — I put it all into a 23-page PDF you can keep open while you work.

Git Mastery Field Guide →

But start here. Get the basics under your fingers first. Everything else builds on top of this.

Questions? Drop them in the comments. There are no silly questions when you're just getting started.

Git as Your Safety Net: The Confidence to Work Fearlessly

Shakil Alam — Sun, 15 Mar 2026 08:29:50 +0000

Part 5 of the Git Mastery Series
← Part 4: Collaboration That Doesn't Create Chaos

By the time most developers reach this level of Git knowledge, they've already had the experience that makes everything click.

Maybe they ran git reset --hard and thought they lost a day's work. Maybe they deleted a branch too early. Maybe a rebase went sideways and they couldn't figure out how to get back to where they started. Maybe they pushed directly to main and spent an hour trying to undo it.

Those moments are terrifying when you don't know about Git's safety nets. Once you do, they become inconveniences — things you recover from in five minutes rather than crises.

This part isn't about new commands to memorize. It's about changing your relationship with Git entirely — from treating it as something to be careful around to using it as the thing that makes you less careful, because you know you can recover from almost anything.

Nothing Is Permanent Until the Garbage Collector Runs

Here's the most liberating thing to understand about Git: deleting a commit doesn't delete it.

When you run git reset --hard HEAD~3, you're moving the branch pointer backward three commits. The three commits you "deleted" are still in the object store. They still exist as objects in the .git folder. They're just not pointed to by any branch anymore.

Git's garbage collector (git gc) runs automatically every few hundred operations or when you explicitly call it. By default, it only removes objects that have been unreferenced for more than 90 days. You have a 90-day window to recover almost anything.

This means: you can be bold. Try risky rebases. Reset commits. Delete branches. Move things around. The cost of being wrong is usually five minutes of recovery, not lost work.

Reflog: Git's Black Box Recorder

git reflog is the command that has saved more careers than any other.

Every time HEAD moves — every commit, checkout, rebase, reset, merge, cherry-pick — Git records it in the reflog. This is completely separate from your commit history. It's a log of every position HEAD has ever been at, including states that no longer have a branch pointing to them.

git reflog

Output:

a3f8c9d HEAD@{0}: commit: fix(auth): handle null token on refresh
1b4e7a2 HEAD@{1}: rebase (finish): returning to refs/heads/feature/auth
9c4d2e1 HEAD@{2}: rebase (pick): feat(auth): add OTP verification
7a5b3f8 HEAD@{3}: rebase (pick): feat(auth): add login endpoint  
2e8d1c4 HEAD@{4}: checkout: moving from main to feature/auth
f3a9b7e HEAD@{5}: reset: moving to HEAD~3
8d2c5a1 HEAD@{6}: commit: add debug logging

See that HEAD@{5} — a reset: moving to HEAD~3? Those three commits you "deleted" are still accessible. HEAD@{6} is one of them. You can get back to that state:

# Recover from that reset
git reset --hard HEAD@{6}

# Or create a branch from that lost commit
git switch -c recovery/lost-work HEAD@{6}

Scenario: you deleted a branch before merging

# Find where the branch was
git reflog | grep "branch-name"
# or just scroll through and find the last commit on it

# Create a new branch at that commit
git switch -c feature/recovered-branch a3f8c9d

Scenario: rebase went wrong

# Before rebasing, note where you are
git log --oneline -1
# a3f8c9d feat: current state

# Rebase goes badly
git rebase main
# This looks completely wrong...

# Go back to before the rebase started
git reflog
# Find the entry just before "rebase (start)"
git reset --hard HEAD@{N}

The reflog only exists locally — it's not pushed to remote. So it won't help you recover something on another developer's machine. But for your own work, it's a complete audit trail.

The Commands That Feel Dangerous (And What They Actually Do)

git reset --hard

This is the one developers fear most. It moves the branch pointer and updates both the staging area and working directory to match the target commit. Any uncommitted changes are gone.

The key word: uncommitted. If your changes are committed, reset --hard doesn't lose them — it just makes them harder to find. Use git reflog to find the commit hash, then git reset --hard <that-hash> to get back.

If you had uncommitted changes, those are genuinely gone from Git's perspective. But your editor's local history (VS Code's timeline, IntelliJ's local history) often has them. Check there first.

git rebase

Rebase feels risky because it rewrites commit hashes. But here's what actually happens: Git creates new commits with the same changes but different parent hashes. The old commits still exist. Before any significant rebase, the reflog has your back:

# If rebase goes wrong, find where you were before it started
git reflog | head -20
# Find the "rebase (start)" entry and look one above it
git reset --hard HEAD@{N}

git push --force

This is actually dangerous on shared branches — you genuinely can overwrite someone else's work. But on your own feature branch? It's routine after an interactive rebase. The safe variant --force-with-lease checks that nobody else has pushed since you last fetched before allowing the force push.

git clean -fd

This removes untracked files and directories. Unlike most Git operations, this is genuinely irreversible — untracked files aren't in Git's object store, so they can't be recovered with reflog. Always run git clean -nd first (the dry run) to see exactly what would be deleted:

git clean -nd  # dry run — shows what would be deleted
git clean -fd  # actually delete

Stash: The Scratch Pad Between Branches

You're halfway through a feature when someone says there's a production bug that needs fixing immediately. Your working directory has changes everywhere. You don't want to commit half-finished work.

# Save current work
git stash

# Switch to main, fix the bug, push
git switch main
# ... fix bug ...
git switch feature/my-feature

# Get your work back
git stash pop

Stash saves your working directory and staging area state, and gives you a clean working directory. git stash pop restores it and removes the stash entry.

A few things most developers don't know about stash:

# Give the stash a meaningful name (you'll thank yourself later)
git stash push -m "halfway through payment refactor"

# See all stashes
git stash list
# stash@{0}: On feature/auth: halfway through payment refactor
# stash@{1}: On main: quick experiment

# Apply a specific stash (without removing it)
git stash apply stash@{1}

# Stash only specific files
git stash push -m "auth changes only" src/auth/

# Stash including untracked files
git stash -u

One warning: stashes are local. They're not pushed to remote. If you stash something on your laptop and switch to another machine, that stash doesn't exist there. Don't use stash as a long-term storage mechanism — it's a scratch pad, not a parking lot.

Cherry-Pick: Taking Exactly What You Need

Sometimes a commit exists on one branch and you need it on another, without merging the whole branch.

You fixed a critical bug on feature/auth but it's not merged yet. You need that fix on main today. Cherry-pick applies the exact changes from that commit onto your current branch:

# Get the commit hash
git log feature/auth --oneline
# a3f8c9d fix(auth): prevent session fixation on login

# Apply it to main
git switch main
git cherry-pick a3f8c9d

Git creates a new commit on main with the same changes but a different hash. The original commit on feature/auth is unchanged.

Cherry-pick is precise and powerful, but use it intentionally. If you find yourself cherry-picking many commits between branches regularly, that's usually a sign your branching strategy has a gap — there should be a path to get those changes merged properly rather than manually copied.

Bisect: Binary Search for the Bug That Snuck In

Something is broken. You don't know which commit introduced it. You know it worked last week. There might be 200 commits between "worked" and "broken."

git bisect runs a binary search through your history, cutting the search space in half at each step. 200 commits becomes 7–8 tests instead of 200.

git bisect start
git bisect bad                     # Current state is broken
git bisect good v2.1.0             # This tag was working

# Git checks out the midpoint commit
# Test your application...
# Working? 
git bisect good
# Broken?
git bisect bad

# After 7-8 steps, Git identifies the exact commit:
# a3f8c9d is the first bad commit

git bisect reset  # Return to original state

If you have a test that can verify the bug automatically, bisect becomes even more powerful:

git bisect run php artisan test --filter=UserAuthTest

Git checks out each midpoint, runs the test, and classifies it automatically. You can walk away and come back to the answer. This is how you debug a regression that crept in across a long sprint — not by reading every commit, but by letting Git find it for you.

Worktrees: Multiple Branches at Once Without Stashing

Here's a scenario: you're deep into a feature branch and need to check something on main — not just look at a file, but actually run the code. Normally you'd stash, switch, run, switch back, pop stash.

git worktree lets you check out a second branch into a separate folder, running both simultaneously:

# Check out main into a separate folder
git worktree add ../project-main main

# Now you have:
# /project              (your feature branch)
# /project-main         (main branch, fully checked out)

# Work in both simultaneously
cd ../project-main
php artisan serve --port=8001

# When done, remove the worktree
git worktree remove ../project-main

Each worktree shares the same .git folder — they're not separate repositories. Changes committed in one worktree are immediately visible in the other. This is particularly useful for reviewing a colleague's PR while staying on your own branch, or comparing behavior between branches in real-time.

Building a Git Workflow You Actually Trust

The developers who use Git most confidently aren't the ones who know the most commands. They're the ones who've built habits that mean they rarely need recovery procedures in the first place.

A few habits that, combined, create a workflow with almost no risk:

Commit often. Small, atomic commits are easier to revert, cherry-pick, and understand. A commit every 30–60 minutes of real work is not too often. It's exactly right.

Branch before you start anything. Ten seconds. Every time. The habit that makes main always deployable.

Push your branches regularly. A branch that only exists on your laptop is lost if your laptop dies. Push feature branches daily even if they're not ready to merge.

Check git status before destructive operations. Before reset --hard, clean -fd, or anything that might lose uncommitted changes, run git status. Take two seconds to read what you'd be throwing away.

Learn git reflog's address by heart. When something goes wrong, git reflog is almost always the first thing to check. It should be a reflex.

The Freedom That Comes From Understanding

The relationship most developers have with Git is one of cautious navigation — running commands that seem to work, avoiding the ones that seem dangerous, hoping nothing goes wrong.

The relationship you can have with Git is entirely different: active, confident, fearless. You run experiments knowing you can undo them. You rebase complex histories knowing you can restore the original with reflog. You delete branches knowing you can recover them from the object store. You reset commits knowing you can find them again.

That confidence changes how you work. You try bolder refactors because you know you can undo them. You explore unfamiliar parts of a codebase more freely because you can revert your exploration. You commit half-finished thoughts because you'll clean them up before the PR.

Git was built to make working with code feel safe. Once you understand it — really understand it, not just the commands but the model — that's exactly what it feels like.

The Complete Recovery Toolkit

# See every position HEAD has been at
git reflog

# Recover from a bad reset
git reset --hard HEAD@{N}

# Recover a deleted branch
git switch -c recovered-branch <hash-from-reflog>

# Undo a commit on shared branch (safe)
git revert HEAD

# Stash and restore work in progress
git stash push -m "description"
git stash pop

# Cherry-pick a specific commit
git cherry-pick <commit-hash>

# Binary search for a breaking commit
git bisect start
git bisect bad
git bisect good <known-good-hash>
git bisect run <test-command>
git bisect reset

# Run two branches simultaneously
git worktree add ../folder branch-name
git worktree remove ../folder

# Dry run before destructive operations
git clean -nd   # Preview what clean would delete
git reset --dry-run  # Not all Git versions support this; use status instead

← Part 4: Collaboration That Doesn't Create Chaos | Back to the Series Hub →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

Collaboration That Doesn't Create Chaos

Shakil Alam — Sun, 15 Mar 2026 08:27:38 +0000

Part 4 of the Git Mastery Series
← Part 3: Branching Without Fear | Part 5: Git as Your Safety Net →

The first time you work on a shared repository with a team, Git feels entirely different. Suddenly the stakes are higher. You're not just managing your own work — you're touching code other people depend on, potentially rewriting history they've already pulled, or introducing changes that conflict with what someone else spent the day building.

Most Git problems on teams aren't technical. They're coordination problems that Git reflects back at you. The branch with 47 commits that's been open for three weeks. The merge that had 12 conflicts because two developers refactored the same file in parallel without knowing it. The force push that rewrote history on a shared branch and caused chaos for the rest of the team.

These situations all had a Git solution. But the solution was mostly about communication and process, not commands.

The Pull Request Isn't a Formality

A lot of teams treat pull requests as a checkbox — open it, someone clicks "approve," merge it. The code review is cursory. Feedback is minimal. "LGTM" appears within minutes on PRs that contain hundreds of lines of changes.

This is a missed opportunity. A pull request is the best point in the entire development process to catch problems — not just bugs, but design issues, architectural drift, security vulnerabilities, and code that technically works but will be unmaintainable in six months.

The problem is that most PRs aren't designed to be reviewed. They're designed to be merged.

What a reviewable PR looks like:

The title is specific: feat(checkout): add Razorpay payment gateway integration not payment stuff.

There's a description that answers: what does this PR do, why was it needed, how should the reviewer test it, and is there anything specific you want feedback on?

The commits tell the story of what was built — not just what you happened to type while building it. (This is why Part 2 matters.)

The PR is a size a human can actually review in 30–60 minutes. If it's 2,000 lines of diff, it's not a PR — it's a project. Break it up.

## What does this PR do?
Integrates Razorpay as a payment gateway option for checkout.
Previously we only supported Stripe.

## Why?
Multiple users in India reported Stripe charges in USD are
causing currency conversion frustration. Razorpay handles INR natively.

## How to test
1. Set RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET in .env (test keys in 1Password)
2. Add an item to cart and proceed to checkout
3. Select "Pay with Razorpay" 
4. Use test card: 4111 1111 1111 1111

## Notes for reviewer
The webhook handling in PaymentController is the most complex part.
I'd appreciate extra eyes on lines 87-134.

Closes #312

That takes five minutes to write and saves the reviewer twenty minutes of confusion. It also forces you to think about whether what you built is actually what was needed.

Keeping Your Branch Current Without Creating a Mess

The longer your feature branch lives, the further it drifts from main. Merge conflicts get worse the longer you wait. Changes other people made become harder to reconcile.

The habit: update your branch from main regularly. Every day, or whenever something relevant lands on main.

Two ways to do this:

Rebase onto main (preferred for feature branches):

git switch feature/my-feature
git fetch origin
git rebase origin/main

Your commits get replayed on top of the latest main. Your branch history stays clean. When you eventually merge, it's a fast-forward. No merge commit, no noise.

Merge main into your branch (simpler but messier):

git switch feature/my-feature
git merge main

This creates a merge commit on your feature branch every time you do it. If you update three times before merging, you have three merge commits on a feature branch. The history becomes confusing. Prefer rebase for this specific operation.

One important rule: if your branch is shared with other developers — if someone else has pulled it and is working from it — don't rebase. Rebasing rewrites commit hashes, which means anyone who has your old commits now has conflicts with the new ones. On shared branches, merge instead.

Protected Branches and Why "No Direct Push to Main" Is a Feature

Most teams eventually learn this lesson the hard way: a direct push to main that breaks the build on a Friday afternoon.

Branch protection rules exist to make mistakes hard by default:

Require pull requests before merging
Require at least one approval
Require CI to pass before merging
Prevent force pushes on main

Setting these up on GitHub or GitLab takes five minutes and prevents a category of incidents that are otherwise entirely predictable.

Settings → Branches → Branch protection rules

The mindset here: protection rules aren't about distrust. They're about creating a system where good practices are automatic and mistakes require deliberate effort to make. A team that needs protection rules isn't a bad team — it's a team that understands that humans make mistakes under pressure and has designed for that.

Force Push: When It's Right and When It's Wrong

git push --force has a reputation as a dangerous command, and it deserves it in the wrong context. But in the right context, it's completely normal.

When force push is right: after rebasing or amending commits on your own feature branch that nobody else has pulled. You've rewritten local history and need to update the remote to match:

git rebase -i HEAD~3  # Clean up commits
git push --force-with-lease origin feature/my-feature

Note --force-with-lease instead of --force. This is strictly safer — it refuses to force push if someone else has pushed to the branch since you last fetched. It protects against accidentally overwriting someone else's work on a shared branch.

When force push is wrong: on main, develop, or any branch other people are working from. Rewriting shared history is how you get frantic Slack messages and conflicts everyone has to manually resolve.

Simple rule: force push only on branches you own. Never on shared branches. If you've accidentally pushed something to a shared branch that needs to be removed — bad credentials, sensitive data, large binary files — have a team conversation before force pushing.

Git Hooks: Automation That Enforces Standards

Git hooks are scripts that run automatically at specific points in the Git workflow. They're one of the most powerful and underused features for teams.

Useful hooks for shared work:

pre-commit: runs before a commit is finalized. Use it to run linters, check for debug statements, validate commit message format:

#!/bin/sh
# .git/hooks/pre-commit
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Fix errors before committing."
  exit 1
fi

commit-msg: validates the commit message format:

#!/bin/sh
# .git/hooks/commit-msg
commit_regex='^(feat|fix|refactor|docs|test|chore|perf)(\(.+\))?: .{1,72}'
if ! grep -qE "$commit_regex" "$1"; then
  echo "Commit message doesn't follow Conventional Commits format."
  echo "Example: feat(auth): add OTP login"
  exit 1
fi

pre-push: runs before pushing to remote. Good for running tests:

#!/bin/sh
# .git/hooks/pre-push
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Fix them before pushing."
  exit 1
fi

The problem with .git/hooks is that it's not committed to the repository — every developer has to set it up manually. For shared hooks, use a tool like Husky (JavaScript projects) or Lefthook (language-agnostic) that stores hooks in the repo and installs them automatically.

The mindset: hooks remove the "I forgot" category of mistakes. Nobody remembers to run the linter before every commit. A hook that does it automatically means the standard is enforced without depending on anyone's memory.

When History Goes Wrong on a Shared Branch

Sometimes, despite good practices, something bad lands on a shared branch. A commit with credentials. A merge that introduced a regression. A massive binary file that shouldn't have been committed.

Reverting vs resetting:

git revert creates a new commit that undoes the changes of a previous commit. It doesn't rewrite history — it adds to it. This is the safe option for shared branches:

# Undo the last commit while preserving history
git revert HEAD
git push origin main

# Undo a specific commit further back
git revert a3f8c9d
git push origin main

git reset moves the branch pointer backward, effectively removing commits from the visible history. This is only safe on branches you haven't shared:

# Undo last commit (keep changes in working dir)
git reset HEAD~1

# Undo last commit completely
git reset --hard HEAD~1

The rule: on shared branches, revert. On private branches, reset.

Tagging: The Commit History Entry Nobody Writes

Tags are a lightweight way to mark important points in history — releases, milestones, deployment checkpoints. Most teams skip them. The teams that use them find them invaluable for production debugging.

# Create a release tag
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# Push all tags
git push origin --tags

# See all tags
git tag

# See what changed between releases
git diff v1.1.0 v1.2.0
git log v1.1.0..v1.2.0 --oneline

When something breaks in production, git diff v1.1.0 v1.2.0 shows you exactly what changed between the version that worked and the version that didn't. Without tags, you're guessing which commits were in which release.

The Collaboration Mindset

Working on a shared repository is a form of communication. Every commit, PR, and branch name is a message to your team. Code that works but is unreadable is a burden. A PR that can't be reviewed is a bottleneck. A force push on main is an interruption to everyone.

The developers who collaborate well with Git aren't the ones with the most commands memorized. They're the ones who think about how their work will land for everyone else. Small PRs that are easy to review. Clear commit messages that explain decisions. Branches that are cleaned up after merging. History that tells the story of how the product was built.

That history outlasts everyone on the team. Write it accordingly.

Quick Reference

# Update feature branch from main (clean)
git fetch origin
git rebase origin/main

# Force push safely after rebase
git push --force-with-lease origin feature/branch

# Undo a commit on a shared branch (safe)
git revert HEAD
git push origin main

# Create and push a release tag
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin v1.2.0

# See what changed between releases
git diff v1.1.0 v1.2.0

# See commits not yet in main
git log main..feature/branch --oneline

# Check what you're about to push
git diff origin/main..HEAD

← Part 3: Branching Without Fear | Next: Part 5 — Git as Your Safety Net →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

Branching Without Fear

Shakil Alam — Sun, 15 Mar 2026 08:27:02 +0000

Part 3 of the Git Mastery Series
← Part 2: Committing with Intention | Part 4: Collaboration That Doesn't Create Chaos →

There's a type of developer who avoids branches. They work directly on main, commit everything there, and nervously push every fifteen minutes so their work is "safe." When asked why they don't branch, they say some version of: "It's just me" or "Branches feel like extra steps" or "I always mess up the merge."

The irony is that branching is exactly what makes Git safe. It's the thing that lets you try something risky without touching working code. It's what lets you switch contexts instantly without losing your place. The developers who are most afraid of Git are often the ones least using the feature that would remove that fear.

What a Branch Is Letting You Do

From Part 1, you know a branch is just a pointer. But let's talk about what that means practically.

When you create a branch and switch to it, you're working in complete isolation. Whatever you commit doesn't touch main. If you decide the whole experiment was wrong, you delete the branch and it's gone. main never knew it existed.

git switch -c experiment/try-new-payment-flow
# ... write code, commit, test, realize it's a bad idea ...
git switch main
git branch -D experiment/try-new-payment-flow
# Gone. main is unchanged.

This is the mental model: a branch is a sandbox. Create one freely for every non-trivial piece of work — a feature, a fix, a refactor, even a quick experiment you're not sure about. The cost is near zero. The safety is real.

A Branching Strategy That Actually Works

There are entire books about branching strategies. GitFlow with its develop, release, hotfix, and feature branches. Trunk-based development. GitHub Flow. They all have tradeoffs.

Here's the one that works for most teams most of the time:

main          → production-ready code, always deployable
feature/*     → new features, branched from main
bugfix/*      → bug fixes, branched from main  
hotfix/*      → urgent fixes, branched from main, merged back immediately

That's it. No develop branch creating a second place to merge things. No release branches unless you genuinely need staged releases. Keep it flat until you have a specific reason not to.

Naming matters more than developers think. feature/user-login tells you everything. feat-login-new tells you something. johns-branch-v2 tells you nothing and will confuse someone three months from now (including John).

# Names that communicate intent
git switch -c feature/razorpay-integration
git switch -c bugfix/cart-total-rounding-error
git switch -c hotfix/payment-crash-on-null-address
git switch -c refactor/extract-notification-service

Merge vs Rebase: Stop Treating This as a Religion

The merge-vs-rebase debate has taken on an almost theological quality in some developer communities. Strong opinions, passionate defense, occasional contempt for the other side.

Here's the practical truth: they're different tools for different situations, and understanding what each one actually does makes the choice obvious.

Merge preserves the full history of how things happened. When you merge feature/login into main, Git creates a merge commit that has two parents — the tip of main and the tip of the feature branch. The history shows exactly when the branch was created and when it was merged. It's honest.

git switch main
git merge feature/login
# Creates a merge commit with two parents

Rebase replays your commits on top of another branch, creating new commits with the same changes but different parent hashes. The result looks like you wrote your feature on top of the latest main, even if main moved forward while you were working. The history is linear and clean. It's legible but slightly fictional.

git switch feature/login
git rebase main
# Replays your commits on top of current main
git switch main
git merge feature/login  # Now a fast-forward, no merge commit needed

When to use each:

Use merge when you're bringing a finished feature into a shared branch. The merge commit is useful — it marks exactly when the feature landed.

Use rebase when you're updating a feature branch to include recent changes from main. This keeps your branch current without a messy "Merge branch 'main' into feature/login" commit polluting the feature's history.

Use merge for public branches. Use rebase for your private, unpushed work. That's the rule that resolves 90% of the confusion.

The Fast-Forward and Why It Matters

When a branch hasn't diverged from its target — meaning main hasn't had any new commits since you branched off — Git can "fast-forward" instead of creating a merge commit. It just moves the pointer forward:

# main: A → B → C
# feature: A → B → C → D → E

git switch main
git merge feature
# Result: main: A → B → C → D → E (no merge commit)

This is why rebasing before merging produces clean history — after a rebase, your branch is always ahead of main with no divergence, so the merge is always a fast-forward.

If you want to force a merge commit even when a fast-forward is possible (to preserve the record that a branch existed), use --no-ff:

git merge --no-ff feature/login

Some teams do this for feature branches so every feature has a visible merge commit in history. Others prefer the clean linear history of fast-forwards. Both are defensible. The important thing is having a consistent team decision rather than random behavior.

Resolving Conflicts Without Panic

Merge conflicts have a reputation they don't deserve. They're not dangerous. They're just Git telling you: "Two people edited the same area of the same file and I don't know which version to keep. You decide."

That's it. Git is asking a question.

When you hit a conflict:

git merge feature/update-user-model
# CONFLICT (content): Merge conflict in src/User.php

Open src/User.php and you'll see conflict markers:

<<<<<<< HEAD
protected $fillable = ['name', 'email', 'phone'];
=======
protected $fillable = ['name', 'email', 'role'];
>>>>>>> feature/update-user-model

The section between <<<<<<< HEAD and ======= is what your current branch has. The section between ======= and >>>>>>> is what you're merging in. You need to edit this into what it should actually be:

protected $fillable = ['name', 'email', 'phone', 'role'];

Then:

git add src/User.php
git commit  # Complete the merge

Three things that make conflicts less painful:

Merge small, merge often. A branch that diverges for two weeks will have far more conflicts than one that diverges for two days. The longer you wait, the more painful the merge.

Use a visual merge tool. git mergetool opens a three-pane editor showing the base, your changes, and theirs. It's significantly easier to understand than raw conflict markers.

Talk to the other person first. The best way to resolve a conflict is to understand why both changes were made before deciding which to keep. A conflict is a conversation waiting to happen.

Deleting Branches: Stop Hoarding

Merged branches should be deleted. Not archived. Deleted.

A repository with 200 stale branches is a repository nobody understands. You can't tell which branches are active, which are abandoned, which are merged. The signal is lost in noise.

# Delete local branch (after merging)
git branch -d feature/login

# Delete remote branch
git push origin --delete feature/login

# See remote branches that no longer exist locally
git remote prune origin --dry-run

Most Git hosts (GitHub, GitLab, Bitbucket) offer "auto-delete branch on merge" in repository settings. Turn it on. Branches should be cheap to create and quick to discard — not collections you maintain.

The One Branch Habit That Changes Everything

Here's the habit that separates developers who love Git from developers who tolerate it: create a branch before you start anything, every time, even for small things.

A "quick fix" that turns into a three-hour debugging session is exactly when you need a branch. A "tiny refactor" that somehow requires touching six files is exactly when you need a branch. An "experimental change" you might want to revert is exactly when you need a branch.

The ten seconds to run git switch -c fix/whatever is worth it every single time. It creates a clean separation between "finished, working code" and "work in progress." It means main is always in a deployable state. It means you can abandon your work cleanly if something higher priority comes up.

Once this habit becomes automatic, Git starts feeling like a safety net rather than a source of anxiety. Because that's what it is.

Quick Reference

# Create and switch to a new branch
git switch -c feature/branch-name

# Switch to existing branch
git switch branch-name

# List all branches (including remote)
git branch -a

# Merge a branch into current
git merge branch-name

# Rebase current branch onto another
git rebase main

# Delete merged local branch
git branch -d branch-name

# Force delete unmerged branch
git branch -D branch-name

# Delete remote branch
git push origin --delete branch-name

# See branches with last commit
git branch -v

# See which branches are merged into main
git branch --merged main

← Part 2: Committing with Intention | Next: Part 4 — Collaboration That Doesn't Create Chaos →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

Committing with Intention: The Art of a Good Commit

Shakil Alam — Sun, 15 Mar 2026 08:26:32 +0000

Part 2 of the Git Mastery Series
← Part 1: How Git Actually Thinks | Part 3: Branching Without Fear →

Six months into a project, you're hunting a bug. You run git log and the history looks like this:

a3f8c9d fix
1b4e7a2 update
c5d2f8a wip
9d3e1f4 asdf
7a2b5c8 final
4f1e8d6 final2
2c9a3b7 ok now it works

Who wrote this? You did. And now you have no idea what any of these commits contain without opening each one individually.

Compare that to this:

a3f8c9d fix(auth): handle expired JWT tokens on refresh
1b4e7a2 feat(cart): add quantity update on product page
c5d2f8a refactor(api): extract payment service into dedicated class
9d3e1f4 fix(checkout): prevent duplicate order on double-click submit

Same code. Same history. The second version is documentation. The first is noise.

The commit isn't just a save point. It's a message to the next person reading this code — which is almost always future you.

What an Atomic Commit Actually Means

"Atomic commit" is one of those terms that gets thrown around without explanation. Here's what it means in practice: one commit, one reason to exist.

Not one file. Not one function. One reason. A refactor and a bug fix are two reasons, even if they touched the same file. A feature and its tests are one reason — the test is part of the feature. Adding a dependency and using it are one reason — the usage doesn't work without the dependency.

The test for atomicity: can you describe what this commit does in one sentence, without using "and"?

✅ "Fix the null pointer exception on empty cart checkout"
✅ "Add email validation to the registration form"
❌ "Fix cart bug and update user model and add some tests"

The second type isn't just harder to describe — it's harder to revert, harder to cherry-pick, harder to understand in code review. Every "and" in a commit description is a sign that the commit should be split.

The Staging Area Is Your Drafting Table

Most developers use git add . for everything and never think about the staging area. This is like writing an entire email in one shot instead of drafting it — it works, but you're not using the tool the way it was designed.

The staging area exists so you can compose exactly what you want in the next commit, regardless of what's in your working directory. You might have three different changes across five files, and you want to commit them separately. The staging area lets you do that.

Stage specific files:

git add src/auth/login.php
git add src/auth/logout.php
git commit -m "feat(auth): add login and logout handlers"

git add src/user/profile.php
git commit -m "feat(user): add profile page"

Stage specific lines within a file — this is the one most developers don't know exists:

git add -p src/user/model.php

This opens an interactive prompt that walks through each change in the file and asks what to do with it:

@@ -15,6 +15,10 @@ class User extends Model
     protected $fillable = ['name', 'email'];
+
+    public function orders() {
+        return $this->hasMany(Order::class);
+    }
+
     public function profile() {

Stage this hunk [y,n,q,a,d,/,e,?]?

Type y to stage that chunk, n to skip it. You can even press e to edit the exact lines you want to stage.

Once you use git add -p regularly, you stop ending up with commits that contain three things that should have been separate. You start thinking in commits while you code rather than after.

Conventional Commits: A Lightweight Standard That Pays Off

Conventional Commits is a simple format that looks like this:

type(scope): description

Optional longer body explaining what and why,
not how (the code shows how).

Optional footer: Closes #123

Common types: feat, fix, refactor, docs, test, chore, perf.

You don't need a tool to enforce this. You just need the habit. What it buys you:

Scannable history. feat vs fix vs refactor gives you instant context when reading git log. You can tell at a glance whether a release was mostly new features or mostly fixes.

Automated changelogs. Tools like semantic-release and conventional-changelog parse commit messages to generate release notes automatically. Your commit messages become your release documentation.

Clearer intent in code review. A PR with commits like feat(payment): add Razorpay integration, test(payment): add unit tests for webhook handler, docs(payment): add setup guide tells the reviewer exactly what to expect in each commit.

Real examples:

git commit -m "feat(auth): add OTP login via Fast2SMS"
git commit -m "fix(cart): prevent negative quantity on decrement"
git commit -m "refactor(api): extract HTTP client into service layer"
git commit -m "chore(deps): upgrade Laravel from 10 to 11"
git commit -m "perf(images): lazy load product images on listing page"

These aren't impressive for their complexity. They're impressive for their clarity. A new developer joining the team can read three months of history and understand what the product has been doing.

Writing the Commit Body: When and Why

The subject line (the -m part) covers the what. The body covers the why. Most commits don't need a body. But when context matters — when a decision isn't obvious, when you're fixing something counterintuitive, when future-you will need context — the body is where that lives.

git commit

This opens your editor. Write the subject, leave a blank line, then write the body:

fix(payment): retry failed Razorpay webhooks on 5xx errors

Razorpay occasionally returns 503 on their webhook endpoint during
high load. Without retry logic, missed webhooks left orders stuck
in "pending" state with no automated resolution path.

Added exponential backoff (3 retries, 2s/4s/8s delays). If all
retries fail, the webhook is queued for manual review.

Closes #247

Six months from now, the person debugging this code will read that and understand not just what changed, but why. That person is almost certainly you.

The rule of thumb: if you had to explain this change in a code review, write that explanation in the commit body. Future developers deserve the same context your reviewer got.

Interactive Rebase: Cleaning Up Before You Share

Here's a common situation: you've been working on a feature for a day. Your commits look like this:

wip: halfway through auth refactor
fix typo
add missing return statement  
actually fix the auth refactor
remove debug logs

This is fine as a work-in-progress history. It's not fine to merge into main. Before opening a pull request, clean this up with interactive rebase:

git rebase -i HEAD~5

This opens an editor showing the last 5 commits:

pick a3f8c9d wip: halfway through auth refactor
pick 1b4e7a2 fix typo
pick c5d2f8a add missing return statement
pick 9d3e1f4 actually fix the auth refactor
pick 7a2b5c8 remove debug logs

Change pick to squash (or s) to fold commits together, reword (or r) to edit a message, drop (or d) to remove a commit entirely:

reword a3f8c9d wip: halfway through auth refactor
squash 1b4e7a2 fix typo
squash c5d2f8a add missing return statement
squash 9d3e1f4 actually fix the auth refactor
squash 7a2b5c8 remove debug logs

Save, close, and Git walks you through editing the final commit message. The result: one clean commit with a proper message, ready to merge.

One rule: only do this on commits you haven't pushed to a shared branch yet. Rewriting history that others have pulled creates conflicts for them. On your local branch before a PR? Rebase freely. On a branch others are working from? Don't touch history.

The Commit as a Unit of Communication

Here's the mindset shift that makes all of this click: a commit isn't a backup. It's a message.

When you write git commit -m "fix", you're not just saving your work. You're writing a letter to everyone who will ever read this codebase — including yourself at 2am six months from now, trying to understand why this line exists.

The developers who write good commits aren't the ones who have more time. They're the ones who've experienced the cost of bad commits firsthand and decided it was worth the thirty extra seconds.

It always is.

Quick Reference

# Stage specific file
git add path/to/file

# Stage specific lines interactively
git add -p path/to/file

# See what's staged vs unstaged
git diff           # unstaged changes
git diff --staged  # staged changes

# Commit with just a subject
git commit -m "feat(scope): description"

# Commit with subject + body (opens editor)
git commit

# Clean up last N commits before pushing
git rebase -i HEAD~N

# Amend the most recent commit (message or content)
git commit --amend

# Undo last commit but keep changes staged
git reset --soft HEAD~1

# Undo last commit and unstage changes (keep files)
git reset HEAD~1

← Part 1: How Git Actually Thinks | Next: Part 3 — Branching Without Fear →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

How Git Actually Thinks (And Why Most Developers Have It Wrong)

Shakil Alam — Sun, 15 Mar 2026 08:25:32 +0000

Part 1 of the Git Mastery Series

Here's a conversation that happens on every development team, roughly once a month:

Someone runs git reset --hard when they meant something else. Or they rebase and the history looks completely wrong. Or they merge a branch and can't figure out why certain changes didn't come through. And then they type something into a chat: "I think I broke Git."

You can't break Git. But you can absolutely confuse yourself when you're working with a mental model that doesn't match what Git is actually doing.

Most Git tutorials teach you commands. Very few teach you how Git thinks. That's the gap this article closes — because once the model clicks, the commands stop being incantations you copy from Stack Overflow and start being decisions you make intentionally.

Git Doesn't Store Diffs. It Stores Snapshots.

This is the most important thing to understand about Git, and it's the thing most tutorials either skip or bury in chapter 10.

When you run git commit, Git does not store "what changed since last time." It stores a complete snapshot of every tracked file in your project at that moment. If a file didn't change, Git doesn't duplicate it — it just points to the same content from the previous snapshot. But conceptually, each commit is a full picture of your project, not a list of changes.

Why does this matter? Because it explains almost everything that confuses people.

When you cherry-pick a commit, Git isn't "moving" changes — it's applying the diff between that commit and its parent onto your current state. When you rebase, Git isn't "moving commits" — it's replaying a series of diffs on top of a new base. When you reset, you're moving a pointer to a different snapshot. Nothing is actually deleted until Git's garbage collector runs.

This is why Git is so powerful — and why operations that sound destructive usually aren't.

The Three Places Your Code Lives

Before any command makes complete sense, you need to know about Git's three areas:

The Working Directory is your actual files — what you see in your editor, what you can run and test. Git is aware of this area but doesn't manage it directly.

The Staging Area (Index) is where you prepare your next commit. When you run git add, you're not committing anything — you're moving changes into a waiting room, saying "include this in the next snapshot."

The Repository (.git folder) is where commits live permanently. When you run git commit, Git takes whatever is in the staging area and wraps it into a new snapshot.

The reason this matters: most developers use git add . and git commit -m as a single motion, without thinking about the staging area at all. That works fine until you need to commit part of a file, undo only part of your changes, or figure out why your commit contains something you didn't intend. At that point, the model saves you.

# See the difference between all three areas at once
git diff           # Working directory vs staging area
git diff --staged  # Staging area vs last commit
git status         # Overview of all three areas

Run these after making some changes. Read the output carefully. You'll immediately see which changes are "in limbo" and which are committed.

Branches Are Just Pointers. That's It.

A Git branch sounds like a complex thing — a parallel universe of code, a separate track of development. The implementation is almost comically simple: a branch is a text file containing a 40-character commit hash.

That's it. A branch is a pointer to a commit. When you make a new commit on a branch, the pointer moves forward to the new commit. When you create a branch, Git copies that pointer to a new file. There's no copying of code. No parallel universe. Just a pointer.

# See exactly what a branch is
cat .git/refs/heads/main
# Output: a3f8c9d1e2b4f6a8c0d2e4f6a8b0c2d4e6f8a0b2

That hash is your entire branch. The branch name is just a human-readable alias for that commit.

This understanding has real consequences. Creating a branch is free — it's instantaneous because you're just writing a file. Switching branches is fast because you're just moving a pointer and updating your working directory to match the target snapshot. "I'll create a branch for this" should never feel like a heavy decision.

HEAD: The Thing That Knows Where You Are

HEAD is one file. It contains either a branch name or a commit hash. It answers one question: "Where am I right now?"

When you're on the main branch and you run git log, you see the history of main because HEAD points to main, which points to its latest commit. When you commit, HEAD moves forward automatically.

cat .git/HEAD
# Output: ref: refs/heads/main

When HEAD contains a branch name, you're in normal mode. When HEAD contains a commit hash directly — not a branch name — you're in "detached HEAD" state. This sounds alarming and isn't. It just means you're looking at a specific commit in history rather than a branch. Make commits in this state and they'll eventually be garbage collected, because no branch pointer moves with you. To keep work done in detached HEAD, create a branch: git switch -c my-new-branch.

How Commits Are Actually Connected

Every commit (except the very first) points to its parent. That's how Git knows what "came before." A commit is an object containing:

A pointer to a snapshot (tree)
A pointer to the parent commit(s)
The commit message
Author and timestamp

# See the raw contents of any commit
git cat-file -p HEAD
# Output:
# tree 8a3f2d9c...
# parent 1b4e7a2f...
# author Shakil <email> 1709123456 +0530
# committer Shakil <email> 1709123456 +0530
#
# feat(auth): add OTP login

The chain of parent pointers is your history. When you run git log, Git starts at HEAD and follows the parent chain backward. When you run git merge, Git finds the common ancestor by walking backward through both chains.

This is why Git operations that seem magical — finding merge conflicts, showing blame, running bisect — are actually mechanical. Git is just traversing a linked list.

Why "I'm Afraid of Breaking Things" Happens

Most Git anxiety comes from not knowing what's recoverable.

Here's the truth: almost everything is recoverable. Commits don't get deleted when you reset — they become unreferenced. They still exist in the .git folder. git reflog shows every position HEAD has ever been at, including commits that no branch currently points to. You have a roughly 90-day window to recover anything before garbage collection runs.

# See everything HEAD has ever pointed to
git reflog

# Output shows a trail of everywhere you've been:
# a3f8c9d HEAD@{0}: commit: fix login bug
# 1b4e7a2 HEAD@{1}: reset: moving to HEAD~1
# c5d2f8a HEAD@{2}: commit: add OTP login

The commit you "deleted" with git reset --hard? It's at HEAD@{1}. Restore it with git reset --hard HEAD@{1}.

The mental shift this creates: Git operations stop feeling like you're working with fragile things that can break. You're working with a database of snapshots, and the pointer that shows you the current view is just one of many pointers. Move it around freely. Almost nothing is permanent until you push — and even then, with force-push access, most things are recoverable.

The Mental Model in One Paragraph

Git is a database of snapshots. Each snapshot (commit) knows its parent. Branches and HEAD are just pointers into this database — they tell you where "now" is, and they move when you make commits. The working directory is your view of one snapshot. The staging area is where you compose the next one. When you understand that commits are permanent, branches are moveable, and HEAD is just your current position — Git stops being a collection of scary commands and starts being a tool you can reason about.

Everything else in Git is built on this. Every command is an operation on snapshots, pointers, or the three areas. The commands that confuse people — rebase, reset, cherry-pick, reflog — all make immediate sense once you can picture what they're doing to the graph.

What to Actually Practice

Open a project — even a test folder with a few files — and spend twenty minutes doing these things while reading the output carefully:

git init
echo "hello" > file.txt
git status                    # See untracked file
git add file.txt
git status                    # See staged file
git commit -m "first commit"
git log --oneline             # See the commit

git branch feature            # Create branch
cat .git/refs/heads/feature   # See it's just a hash
cat .git/HEAD                 # See where you are

git switch feature
cat .git/HEAD                 # Notice HEAD changed

echo "world" >> file.txt
git diff                      # Working directory vs staging
git add file.txt
git diff                      # Nothing — it's staged
git diff --staged             # Staging vs last commit

git commit -m "add world"
git log --oneline --all --graph  # See the branch split

None of this is complicated. But doing it with intention — reading each output, understanding what changed and why — builds the mental model faster than reading any number of tutorials.

Next: Part 2 — Committing with Intention: The Art of a Good Commit →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

Git Mastery: The Complete Series

Shakil Alam — Fri, 13 Mar 2026 18:30:00 +0000

Most Git tutorials teach you commands. This series teaches you how to think — the mental model, the habits, and the confidence that turns Git from something you're careful around into a tool you use fearlessly.

Five parts. Each one standalone. Read in order or jump to what you need.

The Series

Part 1: How Git Actually Thinks
The mental model most tutorials skip — snapshots, branches as pointers, HEAD, and why understanding this changes every command you run. Start here, even if you've used Git for years.

Part 2: Committing with Intention
Atomic commits, the staging area as a drafting tool, conventional commit messages, and interactive rebase for cleaning up before you share. The commit as documentation, not just a save point.

Part 3: Branching Without Fear
Why branching is the thing that makes Git safe. A practical strategy that works for solo developers and teams. Merge vs rebase — not as a religion but as a decision with clear criteria. Resolving conflicts without panic.

Part 4: Collaboration That Doesn't Create Chaos
PRs that actually get reviewed. Keeping branches current without polluting history. Protected branches, Git hooks, tagging releases, and the mindset of writing history that outlasts the team that built it.

Part 5: Git as Your Safety Net
Everything you can recover from and how. Reflog, cherry-pick, bisect, worktrees, stash. The commands that feel dangerous and what they actually do. Building a workflow where almost nothing is truly lost.

Who This Is For

You've used Git. You know add, commit, push, pull. Maybe you've merged a branch and survived a conflict. But some commands still feel like gambles. You copy things from Stack Overflow and hope for the best. Git feels like something you navigate carefully rather than use confidently.

This series is for you.

It's also for developers who use Git every day but mostly at the surface — and want to understand what's actually happening underneath.

How to Read It

Each part builds on the previous one conceptually, but they're each self-contained. If you're curious about one specific topic, jump to that part. If you want the full picture, start with Part 1 — it changes how the rest of the series reads.

The quick reference sections at the end of each part are designed to be bookmarked and returned to.

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

Git for Designers: The Only Guide You’ll Ever Need (Beginner Friendly)

Shakil Alam — Fri, 06 Mar 2026 18:33:29 +0000

If you’re a designer, chances are someone at work has said something like:

“Just push your changes to Git.”

And you probably nodded while secretly thinking…

What exactly does that mean?

Most Git tutorials are made for developers. They dive straight into terminal commands, complex workflows, and technical jargon that makes designers feel like they accidentally walked into the wrong classroom.

But here’s the truth.

You don’t need to become a developer to use Git. You just need to understand what it does and how it fits into your workflow.

Once you get that, Git becomes one of the most useful safety tools you can have when working on websites, UI files, design systems, or anything involving code.

This guide will explain Git in the simplest way possible — without intimidating terms, without unnecessary theory, and without assuming you know how developers think.

What Git Actually Is (Without the Nerdy Explanation)

At its core, Git is just a version history system.

That means it remembers every change you make to your files.

Imagine you’re working in Figma. You design something, then make a few tweaks, then someone asks you to go back to the version from yesterday. Normally that would be stressful.

But Figma has version history, so you can simply roll back.

Git does the same thing — but for files like:

HTML
CSS
JavaScript
images
design assets
documentation

Every time you save progress in Git, it creates a checkpoint in your project’s history.

That checkpoint is called a commit.

Think of a commit like a save point in a video game. If something breaks later, you can jump back to that exact moment.

For designers working with developers, this becomes incredibly useful because it means:

You never lose work
You can undo mistakes
You can see exactly what changed
Teams can work on the same project safely

Without Git, teams often pass files around manually or overwrite each other's work. That’s where things get messy.

Git prevents that.

Git vs GitHub (The Confusion Everyone Has)

One of the biggest beginner confusions is thinking Git and GitHub are the same thing.

They’re not.

The easiest way to understand this is with a simple analogy.

Git is the tool on your computer that tracks changes.
GitHub is where your project is stored online.

A simple comparison designers instantly understand:

Git is like Photoshop.
GitHub is like Google Drive.

Photoshop edits the file.
Google Drive stores and shares the file.

Same thing here.

Git handles version history locally on your computer.

GitHub stores your project in the cloud so your team can access it.

There are other platforms too like GitLab and Bitbucket, but GitHub is the most popular and easiest place to start.

Why Designers Should Care About Git

Many designers think Git is only useful if you’re writing lots of code.

That’s not true anymore.

Modern design work often touches code in small ways:

editing HTML templates
adjusting CSS spacing
working with design systems
updating assets in a project
collaborating with developers

If you make even tiny changes in a project, Git helps protect that work.

It also solves a classic team problem.

Imagine two designers editing the same file. Without Git, one person could accidentally overwrite the other’s work.

Git prevents that by keeping track of who changed what and when.

This transparency makes team collaboration much safer.

First-Time Setup (The Only Technical Part)

Before using Git, you need to install a couple of things. The process is simpler than people expect.

First, install Git on your computer. The official website gives you a quick installer for Windows and Mac, and the setup takes just a minute.

Next, install VS Code if you don’t already use it. Many designers prefer it because it has built-in Git tools and a very clean interface.

Then create a GitHub account. Think of this as your project storage in the cloud.

Once everything is installed, Git needs to know who you are so it can label your commits correctly. That only requires two commands.

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

All this does is tell Git:

“Whenever I save changes, attach my name to them.”

You only do this once.

After that, you’re ready to connect your computer to a GitHub project.

Cloning a Project (Getting the Code)

When you join a project, the first thing you usually do is clone the repository.

Repository sounds fancy but it just means:

The project folder managed by Git.

Cloning simply means downloading that project from GitHub to your computer.

After cloning, you now have the full project locally. From that point on, Git will track every change you make.

How Designers Actually Use Git in VS Code

Here’s the good news.

You don’t need to memorize dozens of commands.

VS Code has a Source Control panel that shows everything visually.

When you edit files, VS Code immediately lists them in the Source Control tab. This panel shows you exactly what changed.

You’ll see:

modified files
added files
deleted files

From there the workflow is very simple.

First you stage the changes you want to save. This basically tells Git which edits should be included in your checkpoint.

Then you write a commit message.

A commit message is just a short note explaining what changed. Something simple like:

“Adjusted button spacing”
“Updated hero section layout”

Once you commit, the change is saved locally in Git history.

The last step is push.

Push uploads your changes from your computer to GitHub so the rest of the team can see them.

That’s it.

Most designers use Git exactly like this.

Understanding Branches Without the Headache

Branches are where many beginners get confused, but the concept is actually very simple.

Think of the main branch as the final version of the project.

You usually don’t edit it directly.

Instead, you create a branch for your work.

The easiest design analogy is this:

Main branch = final Figma file
Branch = duplicate page where you experiment

You work freely on your branch without affecting the main version.

Once your changes are ready, they get merged back into the main branch.

This keeps the project stable while allowing people to experiment safely.

Pull Before Push (The Golden Rule)

If you remember only one thing about Git, remember this rule:

Always pull before pushing.

Pull means downloading the latest changes from GitHub.

Imagine another designer updated the same project while you were working. If you push without pulling first, you might accidentally overwrite their changes.

Pulling first updates your local copy so you’re working with the newest version.

A safe workflow usually looks like this:

Pull latest changes
Make edits
Commit changes
Push to GitHub

Following this routine prevents most problems teams face with Git.

What a Git Conflict Actually Means

The word “conflict” sounds scary, but it’s usually nothing dramatic.

A conflict happens when two people edit the same line in the same file.

Git doesn’t know which version is correct, so it asks you to decide.

You’ll see something like this in the file:

<<<<<<< HEAD
My version
=======
Other designer's version
>>>>>>> branch

Git is simply showing you both options.

You look at the changes, keep the correct one, remove the markers, and save the file.

That’s it.

It’s not an error. It’s Git asking for human help.

Most conflicts are resolved in a minute or two.

Simple Git Habits That Make Life Easier

You don’t need complicated workflows to work safely with Git. Just following a few simple habits makes a huge difference.

Always pull the latest changes before starting work. This ensures you’re not working on an outdated version of the project.

Write clear commit messages so teammates understand what changed without digging through files.

Avoid working directly on the main branch. Creating branches keeps the main project stable.

Commit small changes frequently instead of saving everything at the end of the day. Smaller commits make mistakes easier to undo.

And most importantly, don’t panic when something looks confusing. Git rarely destroys work. Almost everything can be recovered.

The Simple Workflow Designers Should Follow

If you want a safe and reliable Git workflow, stick to this pattern.

Start by pulling the latest version of the project from GitHub. This ensures you’re up to date.

Create a branch for your task so your changes don’t interfere with the main project.

Make your edits normally, whether that’s adjusting CSS, updating layouts, or adding assets.

Commit your changes with a clear message describing what you did.

Push your branch to GitHub so others can see your progress.

Finally, create a Pull Request, which is basically a request asking the team to merge your changes into the main project.

Once it’s reviewed and approved, your work becomes part of the main codebase.

Final Thoughts

Git looks intimidating at first because developers often explain it in complicated ways.

But for designers, Git is really just three things:

A version history tool,
A collaboration safety net,
And a way to protect your work.

You don’t need to learn every command or advanced feature to start benefiting from it. Just understanding commits, pushes, pulls, and branches already puts you ahead of most beginners.

Once you start using Git regularly, it stops feeling like a developer tool and starts feeling like a normal part of your workflow.

And the first time Git saves you from losing hours of work, you’ll wonder how you ever worked without it.

DEV Community: Shakil Alam

The Audit Trail: Building a System That Remembers

What you will build

What an audit trail actually needs to prove

The request ID: one thread through every log

Slow queries: while you are here, add this

The model change logger

File-based logs and the folder segmentation problem

Masking sensitive fields

Where RBAC fits into this picture

What you now have

Before you ship — checklist

Laravel Architecture Patterns for Production

The Four Parts

Part 1 — The Audit Trail: Building a System That Remembers

Part 2 — Queue Architecture: Designing Background Work That Holds Up

Part 3 — Secure File Uploads: Seven Checks and Why Each One Exists

Part 4 — External API Reliability: When Their System Goes Down

How I Reduced Video Storage by 30GB/Day Using FFmpeg and Laravel

Real Numbers from Production

The Problem: Over-Engineered for the Wrong Use Case

Step 1: Research, Experiment, Validate

Step 2: Optimize Video Recording at the Source

Understanding Browser Codec Support (VP8 vs VP9)

The actual recording constraints

Step 3: Compress the Backlog

Layer 1 — Artisan Command

Layer 2 — Queued Job

Layer 3 — Deep Dive into FFmpeg Compression Strategy

Safe Processing with Atomic File Replacement

Step 4: Storage Lifecycle Management (Trash + Cleanup Strategy)

Results

Key Takeaways

Laravel Fast2SMS v2.0.0 — WhatsApp Support, Notification Channels & a Smarter DX

💬 WhatsApp Business API

🔔 Laravel Notification Channels

🧱 Typed Exception Hierarchy

🧪 Rich Fake Assertions for Testing

💡 Fluent Message Builders with Credit Helpers

🛡️ Cost-Saving Guards

⚙️ New Artisan Commands

🚀 Getting Started

Upgrading from v1

Links

Git Explained Simply — For People Who Have No Idea What It Is

What is Git?

Why does this matter?

Git vs GitHub — they are not the same thing

Five words you'll hear constantly

Your first 15 minutes with Git

Step 1 — Install Git

Step 2 — Tell Git who you are

Step 3 — Create your first repository

Step 4 — Add a file and make your first commit

Step 5 — Make a change and watch Git track it

Step 6 — Look at your history

Why two steps? (The staging question everyone asks)

The one habit that makes all the difference

What to learn next

The full Git Mastery Series

Git as Your Safety Net: The Confidence to Work Fearlessly

Nothing Is Permanent Until the Garbage Collector Runs

Reflog: Git's Black Box Recorder

The Commands That Feel Dangerous (And What They Actually Do)

Stash: The Scratch Pad Between Branches

Cherry-Pick: Taking Exactly What You Need

Bisect: Binary Search for the Bug That Snuck In

Worktrees: Multiple Branches at Once Without Stashing

Building a Git Workflow You Actually Trust

The Freedom That Comes From Understanding

The Complete Recovery Toolkit

Collaboration That Doesn't Create Chaos

The Pull Request Isn't a Formality

Keeping Your Branch Current Without Creating a Mess

Protected Branches and Why "No Direct Push to Main" Is a Feature

Force Push: When It's Right and When It's Wrong

Git Hooks: Automation That Enforces Standards

When History Goes Wrong on a Shared Branch

Tagging: The Commit History Entry Nobody Writes

The Collaboration Mindset