DEV Community: Samuel Rouse

XDR - Experience Decision Records

Samuel Rouse — Sun, 08 Nov 2026 16:54:34 +0000

You might be familiar with the idea of an Architectural Decision Record, where the goal is to record both a decision and the underlying reasons to help clarify and shape the design of a project. I'm proposing we implement the same concept for User Experience.

This is not a new thing, really. If you've viewed the Material Design Foundation content, there's information about layout, color, shapes, hierarchy, motion, and more. This content provides a direction and a set of reasons for it.

Your company may have these kinds of rules and reasons for your own interfaces. Most of us don't have Google-level spending, though, so presenting content like the Material UI project is likely out of the question.

In your organization, you may have information shared amongst the UX team but not disseminated out to Developers; or the bare decisions, lacking reasons, may be shared. Both of these create an "information vacuum" where developers may pester the UX team for small, potentially repetitive presentation or interaction rules. Alternately, they may independently make assumptions and create unexpected variations.

"I know the product card expands in 350ms on the search page, but how fast should it expand on the shopping cart?"
"What about the promoted products?"
"I assumed the shopping cart dropdown would be faster than the others."

Making this information available to the developers can free the User Experience team to focus on more complex issues. Developers can exercise reasonable judgement based on not just the rules but the reasons and produce more consistent interfaces with fewer "round trips" to UX for confirmation.

Also, in the age of AI-assisted development, making these resources available in a machine-readable format can improve the ability for coding, review, and validation tools to ensure compliance with the intended UX recommendations.

AI Implementation Support

There is an initial cost of setup and documentation to produce such content, and your team may understandably consider that initial time investment too expensive right now.

However, shards of this information are constantly being delivered in email, chat, online meetings, or documentation for various team members. Modern AI tools may be able to extract proposed decisions and reasons from these various sources, substantially reducing the collection and preparation time for delivering value.

All of this still requires Real Human™ review and approval, and even if the UX team might initially balk at delivering AI-generated or AI-assisted content, being able to share these rules and reasons will reduce the daily load on the team members, putting them in a position to iterate and improve the process and documentation.

Summary

A consistent User Experience is a core deliverable of any product. XDRs offer long-term value and the documentation distributes knowledge more evenly, providing shared resources to create and confirm understanding and support better distribution of decision making.

Ensure consistency with documentation rather than depending on team members to reliably communicate and deliver perfect consistency. And, if applicable, use AI to mine for existing decisions that are not documented in a commonly-accessible location to reduce the effort needed to start sharing your XDRs.

And, as with any good product or policy, be prepared to iterate on the interface or information to suit both the team and the desired outcomes.

Feedback

Does your team have internal design language and patterns? Do they meet your needs for development, quality review, and implementation? Do they communicate their own reasons and limitations? What kind of content do you think could be most valuable in an XDR?

The Discipline of Less: Mies Maxim & the AI Age

Samuel Rouse — Fri, 30 Oct 2026 20:46:16 +0000

AI can build a lot of what we ask for. But can it help us ask for less?

Less is more. — Robert Browning, "Andrea del Sarto" (1855), later adopted as a guiding principle by Mies van der Rohe

I am a User Interface Architect, and I have a tendency to make things complicated. When looking at a defect or new feature, I want to solve every problem the first time. I keep trying to make the One True Design™ that will never need maintenance or updates so long as the physical constants of the universe don't change.

Over time, I have learned to limit myself. Sometimes we just need a first version. Sometimes the best design is the one that does exactly what is needed right now and nothing more. This principle is a constant struggle for me, and AI development can exacerbate that. I’ve seen this across vibe-coded and carefully-planned projects. And the realization that AI can make this worse has me thinking about how to combat it.

The Discipline of Less

Ludwig Mies van der Rohe was a German-American architect who made "less is more" the core of his practice. Buildings like the Farnsworth House are minimal, but not empty. Mies removed elements that did not have a purpose, and what remained needed to provide both value and quality. When the view is the point, use a massive pane of glass rather than a window.

Mies philosophy was that reduction is a form of rigor, and every removal is the result of a decision about what really matters. When AI can build most anything we imagine, this discipline may be essential to building what we need.

Why AI makes this harder

With AI, building is nearly frictionless. A feature that once took days can be generated in minutes, and the cost of adding one more option, one more edge case, one more abstraction has dropped by orders of magnitude, even within the lifespan of LLM-powered development. The old friction that kept complexity in check is gone.

More salient, however, is that an AI will not ask us for justification of a feature. LLMs are sycophantic autocomplete engines, and are designed to give us what we ask for. If we start with an over-complicated concept, AI will do its best to justify our choices, because it is designed to do that for us.

That is why “Mies Maxim” matters more now: not "Can I build this with AI?" but "Does this need to exist?" Because if we fail to ask this question we can be assured that AI won’t push back on the instructions given.

Applying “Less is More” to AI Architecture

While the brainstorming process should have few boundaries, the transition from ideas to implementations needs to have a period of reflection and evaluation. I have some thoughts on how we might apply the Discipline of Less to our projects:

Start with a purpose.
Look for what already exists.
Start simple; then iterate.
Appreciate the pushback.
Treat code as a liability.

Start with a purpose.

Describe the problem and the outcome we need before describing the features we could build. Use an interview process to get to the core of the design. I’ve experienced this misalignment in projects before. Knowing and sharing the goal can help keep you on target and avoid adding or removing the wrong pieces.

Look for what already exists.

Before creating something new, check if a solution exists. Is it close enough? Does it make sense to use that rather than to start fresh? If you can’t incorporate the solution, can you learn from the challenges it has already solved and have it inform your design?

Start simple; then iterate.

Avoid extras and support for cases we do not have yet. Creating a product is a good first step. Then you can add features as they become necessary. This continues to be hard for me…as we start to build I can envision the areas where we might need special solutions. And

Appreciate the push back.

Instruct the LLM to challenge requests, identify unnecessary parts, and propose the smallest version that meets the goal. Maybe even ask it to interview for the justification of a feature. Even when AI can build our whims, we need to put in the mental effort to be in control of our projects.

Just like in real life we sometimes need to be told our idea is too complicated or has issues. The justifications you make can become documentation that helps ensure those concerns and foundations continue to be part of the design and development process.

Treat code as a liability.

Code must be loaded, validated, tested and secured, even when it is unnecessary. Removing the unnecessary makes for a better product and reduces future maintenance costs. And committing -2000 lines of code just feels good, even if AI is doing the reduction.

The test

Before we accept AI output, we can use the Discipline of Less and imagine Mies asking us, “What is left if we take this away?” If the answer is that the product still works and the user is still served, maybe we don’t need it.

AI can help us build faster, but it can also add value if we use it to enforce discipline and make us justify our decisions. Just as AI can run review and analysis of the code, we can use the tools to instill within ourselves and our processes the discipline to build less.

(AI disclosure: The initial draft was written by me, a real human person, then restructured by AI to help shift the message, and then substantially re-written by me, again.)

Blockless Scope: JavaScript Shenanigans

Samuel Rouse — Wed, 27 May 2026 23:29:02 +0000

As a JavaScript developer, you've likely been told that let and const are block scoped. But, how does that work when there is no block?

Classic Example: var vs. let

It doesn't get much more straightforward than this.

// logs 10 ten times
for (var i = 0;i < 10;i += 1) {
  setTimeout(() => console.log(i), 10);
}

// logs 0-9
for (let i = 0;i < 10;i += 1) {
  setTimeout(() => console.log(i), 10);
}

This classic example (which I talked about in Simplify setTimeout) shows a clear example of a variable and a block scope.

But for loops don't need a block statement, they can have a plain statement. So what happens to our block-scoped let when there's no block?

// Still logs 10 ten times
for (var i = 0;i < 10;i += 1) setTimeout(() => console.log(i), 10);

// Still logs 0-9
for (let i = 0;i < 10;i += 1) setTimeout(() => console.log(i), 10);

So...where is the scope?!

Function Scope `var`

For var, nothing changes. It uses only function or global scope. Using var in the for declaration makes the variable available to the containing function or global scope, and the value will persist after the loop completes.

  var a = 1;

  for (var a = 2;a<5;a+=1) console.log(a);

  console.log(a);

var can re-declare variables without throwing errors, so the var a = 2 in the for loop's initialization expression is the same variable as var a = 1 on the first line.

Lexical Scope `let`

This is where it can look confusing, but it's just a special rule of the loop initialization expression.

Variables declared with var are not local to the loop, i.e., they are in the same scope the for loop is in. Variables declared with let are local to the statement.
– MDN, for statement initialization

So while there is no block, there is a scope available exclusively to the statement, whether that's a block statement or not.

Lexical Scope

When we talk about block scope in ES2015+, we're really talking about lexical scope, or the scope as it relates to its surroundings.

The word lexical refers to the fact that lexical scoping uses the location where a variable is declared within the source code to determine where that variable is available.
– MDN, Closures, Lexical scoping

Block scope is a type of lexical scoping. for loop scoping with is another. You can think of this almost like the arguments of a function being available inside the function scope. Function arguments are technically bindings as opposed to variables, but they behave essentially the same.

// Argument a is scoped to the function
[1,2,3].forEach((a) => console.log(a))

// initialization is scoped to the loop statement.
for(let b = 1; b < 5; b += 1) console.log(b);

And, in case you forgot, you can make arbitrary blocks any time you want that have their own scope.

All The Scopes

// Arguments are available to the function scope
function scope(a = 2) {
  console.log(a);

  // Redeclaring the variable in the function scope
  var a = 'a';

  // Function scope
  console.log(a);

  // Redeclaring in the function scope again.
  for (var a = 8; a < 10; a += 1) console.log(a);

  // Function scope
  console.log(a);

  // for statement scope
  for (let a = 1; a < 3; a += 1) console.log(a);

  // Back to the function scope
  console.log(a);

  {
    // Free-floating block with its own scope
    let a = 'random block';
    console.log(a);
  }

  // Back to the function scope
  console.log(a);

  // Access the function scope variable
  for (a = 1; a < 5;a += 1) {
    // var doesn't get block scope, so it is hoisted.
    var b = 2;
    // But let has block scope.
    let c = 3;
    console.log(a, b, c);
  }

  // Access the hoisted variable in the function scope
  console.log(b);

  try {
    // ReferenceError - c was declared in the loop block
    console.log(c);
  } catch(e) {
    // d is scoped to the catch block
    // e is a binding 
    let d = 4;
    console.log(d, e);
  }
}

scope();

// ReferenceError - Not declared in the global scope.
console.log(a);

Conclusion

While we mostly think about block and function scope, there are more scope and special cases, some of which we use probably without even being aware they are different.

for loop initialization expressions provide a special scope to the loop statement, even if the statement isn't a block.

Function arguments are bindings to the function body or the function expression in the case of arrow functions.

Simplify setTimeout

Samuel Rouse — Sun, 17 May 2026 22:27:30 +0000

Hidden in plain sight is a functional programming interface you may have never used, and understanding it can change the way you code. It also fixes a classic JavaScript "gotcha"!

setTimeout is a staple of example code. When simulating asynchronous actions for demos, setTimeout is the go-to function. But there's always a bit of anonymous function boilerplate in the examples.

Classic setTimeout

You've probably seen examples like these many times:

const aPromise = new Promise((resolve, reject) => {
  setTimeout(() => resolve('a value'), 1000);
});

const bPromise = new Promise(function(resolve, reject) {
  setTimeout(function() {
    reject(new Error('oops'));
  }, 1000);
});

In each of these cases we're passing an anonymous function to setTimeout and the function doesn't accept any arguments. Because, where would those arguments come from?!

As it turns out, they come from setTimeout itself! Everything after the first two parameters are passed as arguments to the callback. This lets us lose the anonymous functions and pass parameters that the callback will consume rather than relying on the closure to retain scope.

Functional setTimeout

By passing the parameters to setTimeout, we can eliminate the anonymous function wrapping our action.

const aPromise = new Promise((resolve, reject) => {
  setTimeout(resolve, 1000, 'a value');
});

const bPromise = new Promise(function(resolve, reject) {
  setTimeout(reject, 1000, new Error('oops'));
});

This simplifies writing the code and teaches you to think about the way you use and call functions a bit differently. A lot of coding examples contain anonymous functions like this. Timers, event handlers, promise chains, and regular callbacks.

Functional Thinking

Once you recognize the values are passed in from outside the anonymous function and don't exist because of it, you start thinking more like functional programming.


// Common example promise chain
somePromise
  .then((data) => transformData(data))
  .then((newData) => displayData(newData))
  .catch((err) => console.error(err));

// This works the same way without anonymous functions.
somePromise
  .then(transformData)
  .then(displayData)
  .catch(console.error);

Just as .then and .catch will call an anonymous function, passing it a single argument, it will call the named function and pass it the same argument. The anonymous function doesn't create anything; it lets us "see" the value for ourselves and give them a name temporarily.

Fixing JavaScript Gotchas

Even if you don't see ECMAScript 5 code as often these days you are likely still aware of the lack of block scoping that var has, compared to the ES2015 let and const. This is the classic "gotcha" code example:

// logs 10 ten times
for (var i = 0;i < 10;i += 1) {
  setTimeout(() => console.log(i), 10);
}

// logs 0-9
for (let i = 0;i < 10;i += 1) {
  setTimeout(() => console.log(i), 10);
}

In ES5, we used to "get around" this limitation by passing the variable to a function immediately to ensure the value in the current loop value was consumed instead of the ending value.

function timeoutLogger(value) {
  setTimeout(console.log(value), 10);
}

// logs 0-9
for (var i = 0;i < 10;i += 1) {
  // Current value of i is passed to the function immediately.
  timeoutLogger(i);
}

setTimeout supported these callback parameters for more than a decade before ES2015 was introduced, though. Though our callback runs later, we can call setTimeout immediately and the value is "stored" internally, even without the block-scoped let.

// logs 0-9
for (var i = 0;i < 10;i += 1) {
  setTimeout(console.log, 10, i);
}

No need for extra layers or tricks.

Scopes & Closures

Understanding this option can also help clarify how scopes and closures work.

The var "gotcha" is a problem because of misunderstanding scope and closures. The for loop with var contains a single scope "outside" the loop instances, and because the variable i isn't passed into the anonymous function callback to setTimeout; it closes over the scope of the entire loop and accesses it once it's already finished.

The let solution changes the scope to solve for a developer's incorrect expectation. Each loop gets a separate scope to make sure that asynchronous scope consumers have access to the per-loop value. This isn't really better, just different. The simple example shows it as solving a problem, but it's really a problem of the coding style rather than the language.

Passing the value as a parameter "uses" the value immediately. We don't depend on a closure or a scope, we synchronously execute setTimeout and it consumes the value during the loop where it is called. The same thing happened with the timeoutLogger example. We consumed the value of i synchronously. This created a new scope where it was available to the anonymous function in setTimeout. This is how most asynchronous actions in loops handled the scope prior to ES2015. I can't say I recall any instances of the argument style in "the old days".

Conclusion

This often-overlooked capability of setTimeout both eliminates a common "gotcha" in coding examples and tests, and can help you understand the difference of passed values and scopes/closures better, as well as get you thinking about using functions as arguments directly rather than wrapping them with anonymous functions to help you visualize the inputs and outputs.

If you see this differently, I'd love to hear how you think about it!

Parallel Promises: Then's Second Argument

Samuel Rouse — Thu, 14 May 2026 02:53:14 +0000

You may already know that .then() accepts two arguments:

then(onFulfilled, onRejected)

If either argument is omitted or not a function, it is replaced with an identity or, for rejection, a "thrower".

// Conceptually what `.then()` does with no arguments
.then((x) => x, (x) => { throw x; })

The second argument alone is not only equivalent to .catch(), catch is just a wrapper around .then(undefined, onRejected).

But there's an interesting difference when you specify two: then's second argument is parallel. Not that is operates at the same time, but it creates a different and separate path through the chain. The two arguments are isolated from each other.

Consider this:

// Divergent paths through the code
getUserSettings()
  .then(transformSettings, loadDefaults)
  .then(showSettingsPage)
  .catch(reportError);

Neither of these alternatives are exactly the same:

// Then first
getUserSettings()
  .then(transformSettings)
  // errors in transformSettings will trigger loadDefaults
  .catch(loadDefaults)
  .then(showSettingsPage)
  .catch(reportError);

// Catch first
getUserSettings()
  .catch(loadDefaults)
  // transformSettings will now process defaults
  .then(transformSettings)
  .then(showSettingsPage)
  .catch(reportError);

Using both arguments of .then() allows you to create truly divergent paths purely with promises.

Awaiting Alternatives

You can replicate this with async await, but it either becomes an operation spanning multiple functions, eliminating much of the benefit of async/await, or you have to use extra state to manage it.

// async replacement for action().then(a, b)
// Pass all parts to a helper
async function thenWrap(action, a, b) {
  let data;
  try {
    data = await action();
  } catch (error) {
    return b(error);
  }
  return a(data);
}

Keeping it within one function requires a little extra state to ensure we don't execute the ".then()" after the ".catch()".

async function example() {
  let data;
  let processed = false;
  try {
    data = await action();
  } catch (error) {
    data = b(error);
    processed = true;
  }
  if (!processed) {
    data = a(data);
  }
  // Do more
}

That's Settled

The async solution is a bit like how one might solve the same problem with Promise.allSettled(). Because you always execute the same .then() but you receive an array of objects that communicate success or error, you can mix the declarative functional style of promises and the imperative style of aync/await.

function settledWrap(action, a, b) {
  Promise.allSettled([action()])
  .then(([result]) => {
    if (result.status === 'fulfilled') {
      return a(result.value);
    }
    return b(result.reason);
  });
}

Conclusion

I continue to be a proponent of using promise chains over async/await particularly when it comes to structuring program flow control, as the promise chain can provide a neat abstraction away from the implementation details of the functions.

You can design your functions or program flow to never need the benefit of passing two parallel arguments to .then(), but it can be an elegant solution when you want to keep your code paths separate.

Chaos Proxy: JavaScript Shenanigans

Samuel Rouse — Sat, 27 Dec 2025 20:34:04 +0000

JavaScript Proxies can do almost anything. To demonstrate, let's set up a simple proxy that will sometimes return incorrect values for a proxied function.

Requirements

Accepts a target function
Accepts odds of the error (as a fraction of 1)
Accepts alternative function to execute instead of the normal response.

The Code

Nothing special here. We're just using the apply trap for functions.

const chaosProxy = (source, odds, alternative) => new Proxy(source, {
  apply(target, context, args) {
    return Math.random() - odds >= 0
      ? alternative.apply(context, args)
      : target.apply(context, args);
  }
});

This basic implementation doesn't have much to it. Simple odds calculation, and you execute one function or the other.

Trying It

const circleArea = (radius) => Math.PI * radius ** 2;
const circleAreaClose = (radius) => 3.14 * radius ** 2;

const roughArea = chaosProxy(circleArea, 0.5, circleAreaClose);

roughArea(2); // 12.566370614359172
roughArea(2); // 12.56
roughArea(2); // 12.56
roughArea(2); // 12.56
roughArea(2); // 12.566370614359172

Variations

I'm not going to build these; I leave them as exercises for the reader. Maybe one of these will speak to you and you'll try solving it.

Supporting multiple alternatives with different weights/probabilities.
Support manipulating async/promise values.
Modify arguments objects to see if mutations cause problems in your app.
Return a consistent sequence of responses rather than random ones.
Introduce random delays in asynchronous responses rather than changes.

Conclusion

Sure, there are other ways to go about this, but awareness of different parts of JavaScript can come in handy one day. Don't forget to spend a little time trying things. It can sharpen your skills, broaden your perspective, and help you solve real problems in the future.

Git Bits: Symbols

Samuel Rouse — Tue, 21 Oct 2025 12:59:39 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

Symbols

Some of the confusion around git comes from the different special symbols and references used to navigate through repository history, compare changes between commits, and manipulate branches. These may look cryptic at first, but learning what and how they work can change the way you think about git.

HEAD

Not quite a symbol, but an important foundation. This is the "You are here" sign on the map that is your git graph. HEAD is a reference to the current commit you're working on.

While each branch has a "head" (lowercase) that refers to the latest commit on that branch, the HEAD (uppercase) refers to where you are currently working. While it is most often pointed at a branch, it can point to a tag or a commit as well.

HEAD: The current commit
HEAD^: The parent of the current commit
HEAD@{1}: The previous value of HEAD (where HEAD was before the last command that moved it)

Ancestry References

Needing to traverse the graph happens. Perhaps you need to quickly see if one of your recent changes caused a defect, or you realize you meant to split off a related feature branch three commits ago. These operators allow you to walk the graph.

The Tilde (~) Operator

The tilde operator allows you to reference previous commits – or ancestors – relative to a starting point:

HEAD~1: Refers to the commit one step before HEAD
main~3: References the commit three steps before the tip of the main branch
HEAD~: Shorthand for HEAD~1

# Combine the last 3 commits into one
git reset --soft HEAD~3
git commit -m "Combined commit message"

Branch Prediction

When using the tilde operator, you may run into merge commits. Git follows the first parent in these cases. This is particularly useful when you want to go back in history in a linear fashion.

# Show what was committed one commit ago
git show HEAD~1

# Check out the version from three commits before
git checkout HEAD~3

To help understand, the first parent was the checked out or current branch when the merge happened. Looking back at a merge, you might think of the current branch as the merge destination or receiving branch. When resolving merge conflicts, you may see the terminology "ours" vs. "theirs".

# Checkout "our" branch
git checkout main

# Merge "their" branch into "our" branch
git merge develop

"Our" branch is the first parent in a merge; the checked out branch. "Theirs" is the branch being added.

The Caret (^) Operator

The caret operator also references ancestors but is focused on navigating merge commits:

HEAD^: Refers to the first parent of HEAD (same as HEAD~)
HEAD^2: Refers to the second parent of HEAD (only meaningful for merge commits)
main^^: References the grandparent of the main branch if the last two commits were merges (same effect as main~2)

# Show the first parent of a merge commit
git show HEAD^1

# Show the second parent of a merge commit (the branch that was merged in)
git show HEAD^2

If you are troubleshooting a defect and want to see the state of a feature branch before it was merged into main, you might use ^2 to navigate onto "their" branch without needing to know the branch name or details.

Stacking Symbols

These symbols describe a path through the graph to a particular point. What's more interesting: you aren't limited to one. You can combine a series of traversal operators to get to a specific commit.

# 1. Go back one commit: ~1
# 2. Go back on a merge to the incoming or "their" branch: ^2
# 3. Go back three more commits on that branch: ~3
git checkout HEAD~1^2~3

You won't use this style very often, but I think knowing about it helps understand what's happening. These symbols aren't references to specific things; they are instructions to navigate the history graph. That's why they are called operators: unlike commits which are a state, these represent an action.

If you look at the history like a map, you might read HEAD~1^2~3 like this:

Starting at your current location (HEAD).
Go back one intersection (commit).
Take the other road that merged into this one.
Go straight three more times.

Commit-ish

Not only can you perform these traversal actions from special references like HEAD and branches, you can perform them from any commit or commit-ish reference like a tag.

# Two steps back from a specific commit
git checkout 0269f84~2

# Get "their" branch from a merge commit tagged as v2.1.0
git checkout v2.1.0^2

Range References

Double Dot Notation (..)

The double dot notation helps you see differences between two references:

main..develop: Shows commits that are in develop but not in main
HEAD..origin/main: Shows what commits will be pulled from origin/main

This is one of the most commonly used notations for comparing branches:

# List commits in develop that aren't yet in main
git log main..develop

# See what changes will be pushed to origin
git diff HEAD..origin/main

You can use this style to output a patch file for sharing with others:

git diff HEAD..origin/main > activeWork.patch

Triple Dot Notation (...)

The triple dot notation shows commits that are in either reference but not in both:

main...develop: Shows commits unique to both main and develop
HEAD...FETCH_HEAD: Shows changes between local branch and what was just fetched

This is useful for seeing the complete picture of how two branches diverged:

# See all commits that are in main or develop, but not in both
git log main...develop

# Visualize the divergence between branches
git log --graph --oneline --all main...develop

The @ Syntax

The @ syntax provides a way to reference points in the reflog. Unlike the regular git log, git reflog keeps track of activity on your particular clone of the repo, including branch switches. Navigating through this will be pretty rare, but can be useful for seeing what you've been up to.

main@{yesterday}: Where the tip of main was yesterday
HEAD@{2}: Where HEAD was two moves ago
HEAD@{upstream} or @{u}: The upstream branch of the current branch

# See what the branch looked like yesterday
git show main@{yesterday}

# Compare with what you had yesterday
git diff main@{yesterday}

# Find commit where you accidentally removed code (from reflog)
git log -p HEAD@{2}

Commit Ranges for Operations

These symbols aren't just for viewing history; they're also used for operations:

git rebase -i HEAD~3: Interactively rebase from three commits back
git cherry-pick main..feature: Apply all commits from main to feature onto the current branch
git revert HEAD~5..HEAD~2: Revert a range of commits

When performing operations with ranges, you can use git log --oneline with your range to verify which commits will be affected.

Conclusion

Git's special symbols and revision references let you control how you navigate your repository's history. The syntax might seem arcane at first, but the operators let you navigate, compare, and manipulate your history with precision.

Whether you're analyzing branches, cherry-picking changes, or fixing mistakes in your commits, knowing the symbols puts you in charge of your version control tools.

Author's note: The first draft of this article was produced with the assistance of generative AI.

git commit -am 'Symbols'
git push

Reactive Data With JavaScript Proxies

Samuel Rouse — Tue, 30 Sep 2025 15:58:29 +0000

Stale data is one of the major headaches in modern web development. Especially in React, where hooks require you to manage dependencies manually. Other libraries adopted a variety of techniques to do this automatically.

Libraries that automatically update values when their dependencies change are often referred to as reactive.

JavaScript Proxies provide a lot of interesting capabilities, so today let's take a look at one way we might leverage Proxies to identify and maintain reactive data. We aren't building out an entire framework, but digging into things out ourselves can help us better understand the language and tools we use.

Scope

I want to walk through building a basic data layer with Proxies. I encourage you to take that base and make changes beyond the scope of the article. I use RunJS to write and test the code in this article. It can be a great tool for trying out coding concepts like this, and I recommend it if you want to follow along with each step and try out the code.

Foundation

I'm starting very roughly from a concept I liked from the moment I first saw the Vue library: computed properties. Providing a clear storage distinction between static and computed data, and handling caching and invalidation of these computed values was something that interested me, especially because the consumer doesn't need to know that one is a property and one is a function under the hood.

Proxies are a great tool for this; they can abstract away some of that complexity in the data layer. In fact, Vue 3 uses proxies for reactivity.

I'm not just copying from Vue's design, though. I want to make something of my own to try to understand what is necessary.

Let's dig into some requirements.

Requirements

Create a Proxy object.
When properties are set, separate functions into "computed" and everything else into "static"
Return values when properties are accessed, executing the functions in "computed" through normal property access (no user function calls).
Allow computed functions access to the proxy object so it can consume other values on the object.
Cache function calls so we don't repeat computed work if not necessary.
Track dependencies accessed by computed properties from the proxy.
When properties are updated, use the dependencies information to clear any cached values.

There are more requirements necessary to create a robust, production-ready system, but this is a good starting point.

The Data Underneath

From our requirements, we can gather that we'll need some objects:

static - Static values
computed - Functions for computed properties
cache - Stored results of computed functions
deps - Some way of storing the relationships

I went with deps over dependencies mostly for width considerations in our code. Let's create that starting object.

There are lots of ways we could arrange this data structure, but lets start here.

const source = {
  static: {},
  computed: {},
  cache: {},
  deps: {},
};

Create a Proxy

Proxies accept a target object (or function!) and a handler; an object which defines how the Proxy works. Handlers contain zero or more traps - a term that dates back at least to 1955 which was used to interrupt the usual execution of a program, typically for debugging. These traps will prevent the normal execution of property access to do all the interesting things we want from our Proxy. There are a large number of different traps available to us – the object internal methods - but we're going to focus on get and set.

const data = new Proxy(source, {
  get(target, property, receiver) {
    // Temporarily do the default
    return Reflect.get(target, property);
  },
  set(target, property, value, receiver) {
    // Temporarily do the default
    return Reflect.set(target, property, value);
  },
});

Some notes on these function arguments:

target - The target object specified when we created the proxy. This avoids any need for a closure or external reference to access the original object.
property - The name of the property being accessed on the proxy.
value - For set we need to pass the actual value to be set.
receiver - In some cases we will need to refer back to the object that received the property access request. This – our proxy – is the receiver.

Now we have a proxy object data that will access the target source. It has traps for get and set, but they don't do anything special yet. We've temporarily inserted Reflect calls to provide the original ability of an object getter and setter. At this point the proxy is just a pass-through for normal operations.

// Set a property on the proxy
data.foo = 2;

// The same thing happens on the source
source.foo; // 2

Segmented Set

We specified we want to separate computed functions from static. We could let the user set these directly, but I want to abstract the knowledge of the source object where possible. So let's update the set trap.

const data = new Proxy(source, {
  get(target, property, receiver) {
    // Temporarily do the default
    return Reflect.get(target, property);
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Now it will save values and functions to different places.

// Set a property on the proxy
data.foo = 2;
data.bar = () => 3;

// This goes into values on the source
source.static.foo; // 2

// But we haven't updated our getter
data.foo; // undefined

However, our getter needs work.

Return Values

We have two different places data can live. At first I was tempted to use nullish coalescing to check for static or computed...

get(target, property, receiver) {
  return target.static[property]
    ?? target.computed[property]();
},

But this would cause incorrect behavior for intentional nullish values. We need to use in or, better yet, Object.hasOwn to get values that exist on the correct object, even if they are null, undefined, or falsy.

Return Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      return target.computed[property]();
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Return Validation

You'll notice we executed the computed entry rather than returning the function. This lets us avoid knowing if a value is computed or not.

data.foo = 2;
data.bar = () => 3;

data.foo; // 2
data.bar; // 3

Computed Data Access

Computed values are not very useful if they can't access the other data to perform work, though, so we need to update our get trap to support that change. There are a couple ways we could do that.

We can pass the data proxy to the computed functions as the first argument. This gives them full access to static and computed values. This is where the receiver argument becomes useful.

Computed Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      // Log the computation for demonstration
      console.log(`Computing ${property}`);
      return target.computed[property](receiver);
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Computed Validation

Now, we can use static and computed properties as values.

// Some static values;
data.radius = 3;
data.base = 10;
data.height = 5;

// Some computed values.
data.areaCircle = (data) => data.radius ** 2 * Math.PI;
data.areaRect = (data) => data.base * data.height;
data.areaTriangle = (data) => data.areaRect / 2;

data.radius;       // 3

data.areaCircle;   // 28.274333882308138
'Computing areaCircle'

data.areaRect;     // 50
'Computing areaRect'

data.areaTriangle; // 25
'Computing areaTriangle'
'Computing areaRect'

Note that areaTriangle uses areaRect. Because we passed the proxy and not the "source" object, we can consume computed values inside computed values. But this means we're computing areaRect twice.

Cache Functions

While our examples are pretty trivial, computed values might end be expensive operations, so caching the output will prevent us from doing the same work repeatedly. Adding caching is very straightforward. We can check for a cached value first, and if one is not found perform the work and add it to the cache before returning.

Caching Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      // Log the computation for demonstration
      console.log(`Computing ${property}`);

      const output = target.computed[property](receiver);
      target.cache[property] = output;
      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Cache Validation

Now we'll only process areaRect once. The second time it is accessed, we use the cache.

data.radius;        // 3

data.areaCircle;   // 28.274333882308138
'Computing areaCircle'

data.areaRect;     // 50
'Computing areaRect'

data.areaTriangle; // 25
'Computing areaTriangle'

Track Dependencies

Now we have computed properties and caching, but if we change something our cache can get out of date. A naive cache strategy would be to wipe the whole cache whenever any value is set, but that's not very helpful. What we need is to track our dependencies. And proxies are well-suited to solve this problem.

We've already seen that we can intercept property access with a get trap. So we can see each property that is accessed. We can use a second proxy specific to computed properties to solve this.

Dependency Proxy

const tracker = new Set();
const depsTracker = new Proxy(receiver, {
  get(depTarget, depProp) {
    tracker.add(depProp);
    return depTarget[depProp];
  }
});

This get-only proxy will record each property name accessed using a Set to avoid duplicates. This adds some overhead to using a computed value, but that's why we have caching!

Once we have the tracked dependencies, we can add them to the deps object. Because we're concerned about the dependencies changing, we want the keys inside deps to be the properties we depend on. We can take the tracker and populate deps from it.

tracker.forEach(dependency => {
  target.deps[dependency] ??= new Set();
  target.deps[dependency].add(property);
});

// Something very roughly like this
const deps = {
 radius: ['areaCircle'],
};

Dependency Code

Let's put that all together. I've also eliminated the console.log in the computed logic. Adding log statements can help you understand the order of operations, but you can add your own if you are interested.

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      const tracker = new Set();
      const depsTracker = new Proxy(receiver, {
        get(depTarget, depProp) {
          tracker.add(depProp);
          return depTarget[depProp];
        }
      });

      const output = target.computed[property](depsTracker);
      target.cache[property] = output;

      tracker.forEach(dependency => {
        target.deps[dependency] ??= new Set();
        target.deps[dependency].add(property);
      });

      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Validated Dependencies

Now, let's run the same code:

// Some static values;
data.radius = 3;
data.base = 10;
data.height = 5;

// Some computed values.
data.areaCircle = (data) => data.radius ** 2 * Math.PI;
data.areaRect = (data) => data.base * data.height;
data.areaTriangle = (data) => data.areaRect / 2;

data.radius;       // 3
data.areaCircle;   // 28.274333882308138
data.areaRect;     // 50
data.areaTriangle; // 25

And check our deps object:

source.deps;

{
  radius: Set(1) {
    'areaCircle',
  },
  base: Set(1) {
    'areaRect',
  },
  height: Set(1) {
    'areaRect',
  },
  areaRect: Set(1) {
    'areaTriangle',
    }
  }
}

We can see that we tracked each direct dependency. We aren't using that information, yet, just collecting it, so we'll need to look at our set trap for that.

Clear Cache

When we call set we know the property that is changing, so it's a perfect time to check the deps to see if we need to remove anything from the cache.

set(target, property, value, receiver) {
  // Make a function for recursion
  const depClean = (prop) => {
    target.deps[prop]?.forEach(dep => {
      delete target.cache[dep];
      depClean(dep);
    });
  };

  depClean(property);

  if (typeof value === 'function') {
    target.computed[property] = value;
    return value;
  }
  target.static[property] = value;
  return value;
},

We created a small recursive function to ensure any nested dependencies – like areaTriangle – are cleared. We didn't bother with any "exists" checks beforehand. A property should have no dependencies to check if it is being set for the first time.

Invalidation Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      const tracker = new Set();
      const depsTracker = new Proxy(receiver, {
        get(depTarget, depProp) {
          tracker.add(depProp);
          return depTarget[depProp];
        }
      });

      const output = target.computed[property](depsTracker);
      target.cache[property] = output;

      tracker.forEach(dependency => {
        target.deps[dependency] ??= new Set();
        target.deps[dependency].add(property);
      });

      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    // Make a function for recursion
    const depClean = (prop) => {
      target.deps[prop]?.forEach(dep => {
        delete target.cache[dep];
        depClean(dep);
      });
    };

    depClean(property);

    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Invalidation…Validation

Let's perform some operations to populate the cache, and then prove that the cache is cleared base on dependencies.

// Access properties to create cache entries
data.radius;       // 3
data.areaCircle;   // 28.274333882308138
data.areaRect;     // 50
data.areaTriangle; // 25

// View the cache
source.cache;

{
  areaCircle: 28.274333882308138,
  areaRect: 50,
  areaTriangle: 25
}

// Change a property with dependencies
data.base = 8;

// View the updated cache
source.cache;

{
  areaCircle: 28.274333882308138
}

We can see that changing base cleared both areaRect and areaTriangle, so our recursive dependency check worked.

Now, if we call those computed properties again, their values should change.

data.areaRect;     // 40
data.areaTriangle; // 20

Result

We've now worked through each of our requirements, and we have a basic reactive data model. We can support static and computed properties. We can access computed properties without knowing there are functions underneath. We cache those computed values, and create a dependency tree that lets us invalidate that cache when properties are updated.

Let's take a look at the completed code.

const source = {
  static: {},
  computed: {},
  cache: {},
  deps: {},
};

const data = new Proxy(source, {
  get(target, property, receiver) {
    // Check for static properties first
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    // Check the cache for saved computed properties
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      // Build the dependencies and cache the compute value
      const tracker = new Set();
      const depsTracker = new Proxy(receiver, {
        get(depTarget, depProp) {
          tracker.add(depProp);
          return depTarget[depProp];
        }
      });

      const output = target.computed[property](depsTracker);
      target.cache[property] = output;

      tracker.forEach(dependency => {
        target.deps[dependency] ??= new Set();
        target.deps[dependency].add(property);
      });

      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    // Use recursion to clean nested dependencies
    const depClean = (prop) => {
      target.deps[prop]?.forEach(dep => {
        delete target.cache[dep];
        depClean(dep);
      });
    };

    depClean(property);

    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Proxy Proof-of-Concept

All this in under 60 lines of code! While it doesn't do everything, proxies provided us the tools to build a system to support automatic dependency detection and caching quickly and relatively easily.

Your Turn?

There are plenty of things to add and improve in this design. Try your hand at adding onto the code and see where it takes you.

Add support for in and Object.keys from the proxy.
Add support for deleting properties.
Clean up dependencies when a property is deleted.
Only calculate the dependencies when the computed property changes.
Support changing properties from static to computed or vice versa.
Avoid dependency checks on initial set?
Should we re-compute values when dependencies change, or wait for them to be accessed?

Conclusion

Proxies provide nearly unlimited flexibility in JavaScript. Starting from a rough idea we built up a reactive data layer with caching and dependency tracking.

I hope you found this article interesting. Are there better ways to create this functionality? Is part of this confusing and needs better explanation? Let me know!

Promise Hashes

Samuel Rouse — Sun, 28 Sep 2025 00:17:52 +0000

Promises provide powerful asynchronous program flow-control, but one of the things they do not currently handle are maps/hashes of promises. Promise.all() accepts an array, but it can be cumbersome to track things by index when multiple async actions are needed, e.g. setting up a form or executing an action that requires permissions.

It would be nice, sometimes, to be able to pass a named object instead of an array.

// An imaginary future where this concept exists
Promise.hash({
  config: getAppConfig(),
  i18n: getFormattingDirectives(),
  l10n: getLocaleStrings(),
  permissions: getPermissions(),
  rules: getFormRules(),
});

While we don't have such a method, creating one turns out to be really straightforward. Let's take a look.

Requirements

Accept a "promise hash" – an object with key-value pairs where the values may be promises.
Extract the values as an array and pass them to Promise.all().
If successful, re-connect the array of results with the original keys and return this new "value hash". Otherwise, pass the rejection.
Return the promise chain containing the "value has" object.

Not All Promises

Note the word may in the first requirement. If you aren't familiar with the inner workings of Promise.all() you might not know that it accepts non-promises and treats them the same as resolved promises. This provides flexibility so a function can be asynchronous or not.

Promise.all([
  // Immediately resolved promise
  Promise.resolve(1),
  // Normal values or function returns are treated as "resolved"
  2,
  // A promise with a little delay
  new Promise(res => setTimeout(res, 100, 3)),
  // This function is returned as a value, not executed
  (a) => a + 2,
]).then(console.log);
// [1, 2, 3, ƒ() ])

This isn't something you have to worry about, but it can really come in handy when testing & mocking, as you don't have to create async functions if they don't initiate promise chains.

Coding

Now, let's build based on our requirements.

Accept a "promise hash"

Not much to accomplish in this step.

const promiseHash = (inputHash) => {};

Extract the values...to Promise.all()

Updated versions of JavaScript make this quite simple:

const promiseHash = (inputHash) => {
  Promise.all(Object.values(inputHash));
};

If successful...return the new "value hash"

const promiseHash = (inputHash) => {
  Promise.all(Object.values(inputHash))
    .then(results => {
      const keys = Object.keys(inputHash);
      const entries = results
        .map((value, index) => [keys[index], value]);
      return Object.fromEntries(entries);
    });
};

You'll notice we didn't do anything about rejection handling. We get that "for free" with Promise.all(). The first promise to reject gets the rejection, so that is passed through automatically.

Return the promise chain


const promiseHash = (inputHash) => Promise 
  .all(Object.values(inputHash))
  .then(results => {
    const keys = Object.keys(inputHash);
    const entries = results
      .map((value, index) => [keys[index], value]);
    return Object.fromEntries(entries);
  });

There's not a lot to it. The object prototype methods really simplify the transformation from and to object for us.

Hardening

I'm going to pause here for a change. While this meets our requirements, there's a time difference between when we extract the keys and values. This is unlikely to cause a problem, but it can if we modify the inputHash object before the promises resolve.

To prevent this, even from intentionally mischievous code, we can use Object.entries() to extract the matching pairs only once to ensure they always line up. We could do this more efficiently but I'd be more concerned about the consuming code if we get to a point where the object hash transform is a performance issue.

const promiseHash = (inputHash) => {
  // Convert the object once for stable ordering.
  const entries = Object.entries(inputHash);
  // Split keys and values
  const keys = entries.map(([key]) => key);
  const values = entries.map(([, value]) => value);

  // Merge the results and keys back together
  return Promise.all(values)
    .then(results => Object.fromEntries(results
      .map((result, index) => [keys[index], result])));
};

We could write the last bit differently, depending on your comfort reading nested function operations:

  // Merge the results and keys back together
  return Promise.all(values).then(results => {
    const valueHash = results.map((result, index) => [
      keys[index],
      result,
    ]);
    return Object.fromEntries(valueHash);
  });

Example

A simple demonstration of the design:

const hash = {
  a: Promise.resolve(1),
  b: new Promise((res) => setTimeout(res, 100, 2)),
}

promiseHash(hash).then(console.log)
// { a: 1, b: 2 }

Use Cases

Every now and then I see a group of similar requests in a Promise.all()...

const entitlements = Promise.all([
  getUserPermissions(),
  getPostPermissions(),
  getModeratorPermissions(),
]).then(([ userPerms, postPerms, modPerms ]) => {
  if (userPerms.canEdit) {
    // ...
  }
});

This pattern is brittle. It depends on the developer keeping two "unrelated" arrays in sync. If we add, remove, or rearrange the entries, we can unintentionally change or break the application.

const entitlements = Promise.all([
  // Adding an entry out-of-order breaks the .then()
  getAdminPermissions(),
  getUserPermissions(),
  getPostPermissions(),
  getModeratorPermissions(),
]).then(([ userPerms, postPerms, modPerms ]) => {
  if (userPerms.canEdit) {
    // ...
  }
});

Hashes prevent this problem.

const entitlements = promiseHash({
  // Adding a key doesn't change the .then()
  admin: getAdminPermissions(),
  user: getUserPermissions(),
  post: getPostPermissions(),
  mod: getModeratorPermissions(),
]).then((perms) => {
  if (perms.user.canEdit) {
    // ...
  }
});

Variations on a Theme

We could also use Promise.allSettled() underneath this design instead of Promise.all().

const promiseSettledHash = (inputHash) => {
  // Convert the object once for stable ordering.
  const entries = Object.entries(inputHash);
  // Split keys and values
  const keys = entries.map(([key]) => key);
  const values = entries.map(([, value]) => value);

  // Merge the results and keys back together
  return Promise.allSettled(values)
    .then(results => Object.fromEntries(results
      .map((result, index) => [keys[index], result])));
};

We could even make this an optional second argument so you can choose which operation handles your hash.

const promiseHash = (inputHash, useSettled = false) => {
  // Convert the object once for stable ordering.
  const entries = Object.entries(inputHash);
  // Split keys and values
  const keys = entries.map(([key]) => key);
  const values = entries.map(([, value]) => value);

  // Merge the results and keys back together
  return (useSettled
    ? Promise.allSettled(values)
    : Promise.all(values)
  ).then(results => Object.fromEntries(results
    .map((result, index) => [keys[index], result])));
};

You'll note that we included the full name in each call. Promise methods must be called on the Promise object, so the alternate code below throws an error.

(useSettled ? Promise.allSettled : Promise.all)(values)
// TypeError: Promise.all called on non-object

Summary

Honestly, there isn't that much to creating a Promise hash, but it can be a useful tool if you find yourself collecting a few promises. There may be other ways to design your application design to avoid the Promise.all() risks, but a simple wrapper to provide hash support can make your code a little easier to follow.

Git Bits: The Graph

Samuel Rouse — Sat, 20 Sep 2025 17:47:27 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

The Graph

The foundation of git is a directed acyclic graph. You can dive into the Wikipedia article for more information than you probably want, but the basics as they relate to Git are this:

Each commit in a Git repo is a node on the graph.
Each commit "knows about" (references) the one or more nodes that came before it.
We can trace the history of commits through the graph.
We can't go backward, so there are no loops, but it is possible to have multiple paths between two nodes.

Notes about Graphs

Fig.1 - Example graph of commits on multiple branches

This graph was created with the absolutely amazing Mermaid.js. It represents commits with a number and a hash by default, like 0-2b99de5. The number is the order they appear in the graph definition. The hash is a randomly generated hexadecimal to simulate what actual hashes in git look like.

Nodes

There are mostly two types of "nodes" on the graph in git: commits and merges.

You can see that 2-a0f289f on the develop branch has a line that leads back to 1-10ed042, which in turn has a line that leads back to 0-2b99de5, the start of this graph. You can walk the graph and see the history of each commit in this way.

Merges

Fig.2 - Example graph pointing out a merge commit

Looking at the graph, you can see a node where the changes from the feature branch are merged into develop. That node is connected to two parents: 5-ca2ed61 on develop and 6-fdcd8eb on feature.

It is possible to perform a merge of more than two sources – an "octopus merge" – but it is very uncommon.

Branches

Git's branching system is sometimes referred to as lightweight branching. Compared to some version control systems which make whole copies for new branches, git branches are essentially just a pointer to a commit on the graph, so making a new branch is basically instantaneous. Let's see that in action.

I've created an empty repo and committed a simple README file. If I run git log, it gives me the commit.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> main)
Author: Me <me@example.com>
Date:   Fri Sep 19 12:10:39 2025 -0400

    Initial commit

If I make a new branch with git branch develop and run git log again, I see that this same commit is now represented on main and develop.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> main, develop)
Author: Me <me@example.com>
Date:   Fri Sep 19 12:10:39 2025 -0400

    Initial commit

Even though I've created a branch, I haven't changed the contents of the repo. The branch is metadata – information about the commits.

Divergence

Interestingly, the branch doesn't keep track of every commit on it. The branch only has to know about the latest commit, because that one knows about the commit that came before it, and so on.

Going back to our branch diagram from earlier, the develop branch can build the list of commits in its history, and discover where it has one in common with main – 0-2b99de5, so we can say develop diverged from main at 1-10ed042.

Timeless Representation

One important distinction is that time is not actually a necessary part of the graph. We think of them in time order because it's helpful to us, but the graph is really only concerned with direction.

The HEAD

While there are timestamps on commits, there's really only one time git is interested in: right now. Git represents "wherever you are right now" as a value called HEAD.

If we look at that git log command again, we can see that HEAD is pointing to the main branch, even though we also created a develop branch.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> main, develop)

If we git checkout develop we'll still be on the same commit, but HEAD will be different.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> develop, main)

You can use commands to move back from HEAD, like git checkout HEAD~1 which will check out one commit before the current HEAD.

Re-writing History

The Graph keeps track of the relationship between things, but it is not written in stone. There are several ways you can change the past, but, just as in the movies, there are risks of doing so.

Most of the concerns with re-writing history are around shared branches. Because git is decentralized, there isn't something that says which history is correct if histories diverge. You create a different timeline that didn't happen for everyone. It's a science-fiction nightmare, but for code.

Still, when you are on your personal branch, re-writing history can be really useful.

git commit --amend let's you change the last commit you created. If you misspelled a word or forgot an update, --amend can let you create a history where that didn't happen. For simple changes that exist only for you, this is an easy way to avoid having a commit with an obvious error.

Rebase

Rebasing has a bad reputation. Rebasing is when you change history by "moving the start of your branch". This usually happens during parallel development when two or more people are submitting changes to a branch or repository. When one developer's work is accepted and merged, another developer may need to incorporate that work.

Fig.3 - Branch feature1 is merged in while we are working on feature2

Now that feature1 is merged, we have a couple options. We could create a merge from main to feature2 with git merge main while we are on the feature2 branch.

Fig.4 - Merge main into feature2

If feature2 is a branch that multiple people are working on, that's usually the correct solution. But if it's just one developer, using git rebase main creates a "cleaner" history, because there is no longer a point where history diverged.

Fig.5 - Rebase feature2 onto main

We can say, "feature2 was rebased onto main." History has changed, and there is no record that it was ever attached to the earlier commit.

We'll talk more about rebasing another time. But from the simple diagrams we can see that rebase picks up part of the graph and connects it somewhere else.

Resources

Some information in this article comes from the unassailable git-scm.com site and the Pro Git Book available to read there for free.

The section Branches in a Nutshell provides some really good detail and diagrams on the graph and branching.

Summary

Let's bring it back together. Git is a directed graph of commits, each representing a snapshot of the repo. Branches and tags are metadata that point to specific commits. You can add to, change, or even move parts of the graph.

git commit -am 'The Graph'
git push

Git Bits: Basic Terminology

Samuel Rouse — Fri, 19 Sep 2025 10:00:00 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

Working Words

The decentralized nature of Git creates some confusion about the different words you might use, so let's try to clear that up.

Repo

Repository, or repo, is the place data is stored. People sometimes will use "project" interchangeably with a repo. The repo usually contains the project history.

When you work with a project on GitHub, there is a repo on the server. When you clone that repo, there is a repo on your computer as well.

A server isn't necessary, though. If you run git init you create a new repo on your computer. It doesn't exist anywhere else in that moment.

Clone

We usually refer to our copy of a repo as a clone. This helps differentiate between our copy and the server. While there is no actual distinction, we tend to still think in that centralized concept, so most people refer to the server's copy as the repo.

Fork

Forking is the idea that you split from the original repo and have your own copy. Perhaps you want to do something different with the project, or this can be the first step in making a copy so you can contribute in the open-source fork-and-pull model.

This terminology is really about the centralized server-side repositories. Clones are for working with the original server-side repository. Forks are making a copy of that server-side repository.

Remote

A remote is another copy of the repo, usually on a server. When you clone a repo, it will create a default remote of origin pointing back to the source. In many branch-based workflows, you only set up one remote. In a fork-and-pull style, you might set up origin for your personal fork and upstream for the repository you forked from.

Summary

Does this line up with how you use these words? Let me know!

git commit -am 'Basic Terminology'
git push

Git Bits: Working Without a Server

Samuel Rouse — Thu, 18 Sep 2025 17:14:39 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

The Server Is Optional

Git is a distributed version control system. Most of the time this isn't very relevant, because we usually work with a single, central repository, but we don't have to. Because we clone the whole repo to our computers, each copy contains everything.

Unlike centralized version control, you don't have to stop collaborating when the server goes down. You can still sync and share and merge work directly with other developers, whether there's an outage or you are working in an environment without Internet access.

Decentralized Differences

This disconnect from "traditional" centralized version control systems dating back to the 1960s can be hard to grasp, as git isn't like most of our models of servers we connect to. We download and view content from a web server, but the server remains the "source of truth". If we make a post or comment on this site, they are stored on the server, not our computer.

You might think of git repos more like operating systems. The device where you are reading this has a full copy of its operating system. It might pull updates from a server, but we each have a whole "working copy" of the OS.

It's more than that, because programs and operating systems are generally artifacts (outputs) of development, and git typically stores the source (inputs).

Going Serverless

Git supports connections using https:// and ssh:// – and its own git:// protocol – but also a local file protocol which allows you to push and pull from the file system. If your repository server is down, you can still share work with others.

# Set up a file system remote
git remote add teammate /Users/alex/work/project

# Load and merge your team's updates
git fetch teammate
git merge teammate/main

Git even supports offline transfer of updates using git-bundle, so you can bundle up changes from a common point that you know another person has in their local clone of the repo, and send them the changes. This was the original use of git. Make changes, bundle them into a patch file, and send them off to a maintainer of the project.

All you need is two laptops and a flash drive to use this flow.

# Bundle the differences between main and my feature
git bundle create updates.bundle main..feature

# Merge in a bundle
git pull path/to/updates.bundle main

Summary

Each Git clone is a complete repository with its own history. Two developers can collaborate using the local file protocol or by exchanging offline bundles. The server is convenient but not required.

git commit -am 'Working Without a Server'
git push

DEV Community: Samuel Rouse

XDR - Experience Decision Records

AI Implementation Support

Summary

Feedback

The Discipline of Less: Mies Maxim & the AI Age

The Discipline of Less

Why AI makes this harder

Applying “Less is More” to AI Architecture

Start with a purpose.

Look for what already exists.

Start simple; then iterate.

Appreciate the push back.

Treat code as a liability.

The test

Blockless Scope: JavaScript Shenanigans

Classic Example: var vs. let

Function Scope var

Lexical Scope let

Lexical Scope

All The Scopes

Conclusion

Simplify setTimeout

Classic setTimeout

Functional setTimeout

Functional Thinking

Fixing JavaScript Gotchas

Scopes & Closures

Conclusion

Parallel Promises: Then's Second Argument

Awaiting Alternatives

That's Settled

Conclusion

Chaos Proxy: JavaScript Shenanigans

Requirements

The Code

Trying It

Variations

Conclusion

Git Bits: Symbols

Symbols

HEAD

Ancestry References

The Tilde (~) Operator

Branch Prediction

The Caret (^) Operator

Stacking Symbols

Commit-ish

Range References

Double Dot Notation (..)

Triple Dot Notation (...)

The @ Syntax

Commit Ranges for Operations

Conclusion

Reactive Data With JavaScript Proxies

Scope

Foundation

Requirements

The Data Underneath

Create a Proxy

Segmented Set

Return Values

Return Code

Return Validation

Computed Data Access

Computed Code

Computed Validation

Cache Functions

Caching Code

Cache Validation

Track Dependencies

Dependency Proxy

Dependency Code

Validated Dependencies

Clear Cache

Invalidation Code

Invalidation…Validation

Result

Proxy Proof-of-Concept

Your Turn?

Function Scope `var`

Lexical Scope `let`