Tech Blog

Rebase cheat sheet

2025-04-15T00:00:00Z

    gitGraph LR:
       commit id: "C1"
       commit id: "C2"
       branch "topic"
       commit id: "C3"
       commit id: "C4"
       checkout main
       commit id: "C5"
       commit id: "C6" tag: "HEAD"

# git rebase main topic
$ git checkout topic
$ git rebase main

    gitGraph LR:
       commit id: "C1"
       commit id: "C2"
       branch "old topic" order: 3
       commit id: "C3"
       commit id: "C4" tag: "ORIG_HEAD"
       checkout main
       commit id: "C5"
       commit id: "C6"
       branch "topic"
       commit id: "C3′"
       commit id: "C4′" tag: "HEAD"

Welcome to your new blog

2025-01-01T09:00:00Z

This is a starter post for the eleventy-tech-blog template. It exists to show off the formatting the template supports, so you can delete it once you’ve seen what’s available.

Text and code

Inline code looks like this, and fenced code blocks get syntax highlighting:

export function greet(name) {
  return `hello, ${name}`
}

Footnotes

You can drop a footnote right into a sentence like this one.⁽¹⁾ They render at the bottom of the post and link back up to where they were used.

Tables

Feature	Supported
Syntax highlighting	yes
Footnotes	yes
Mermaid diagrams	yes

Diagrams

This template can render Mermaid diagrams directly from a fenced code block:

graph LR
  A[Draft] --> B[Review]
  B --> C[Publish]

Replace this post — and the others in content/posts/ — with your own writing whenever you’re ready.

Like this. Footnote text can contain its own links and formatting. ↩︎

Dot Dot notation

2020-04-26T02:00:00Z

OK, seriously? What is it with the dot notation in git? Given this repo:

             master
               |
C1---C2---C5---C6
      \
       C3---C4
            |
          topic

How does git log master..topic mean to display commits C3 and C4?

Let’s see if we can make things simpler.

A simple case

Imagine a repo with two branches, master and topic. The topic branch branches off of master, but there are no new commits on master:

             master
               |
L1---L2---L3---L4---L5---L6
                         |
                       topic

The git log output looks like this:

$ git log --oneline --all --graph --decorate
* 0c1d724 (topic) L6
* 5d4cdb5 L5
* ca8cf0a (HEAD -> master) L4
* 019e663 L3
* b1ea04d L2
* 83fd5ca L1

What should we expect the output of git log master..topic to be?

$ git log --oneline --graph --decorate master..topic
* 0c1d724 (topic) L6
* 5d4cdb5 L5

That looks right. The commits from master to topic are L5 and L6 (not including the L6 commit at master).

OK. What if we reverse the order of the commits?

$ git log --oneline --graph --decorate topic..master

Order matters. The dots seem to denote the passage of time. So master..topic means:

The commits from master to topic.⁽¹⁾

Then it makes sense that topic..master produces no output because

the commits from topic to master

is nonsensical since topic comes after master.

Now with branches

Let’s go back to our first repo:

             master
               |
C1---C2---C5---C6
      \
       C3---C4
            |
          topic

What does git log master..topic, mean in this case? Commits from master to topic doesn’t make a lot of sense here.

It turns out that master..topic is shorthand for

^master topic

See, git log doesn’t work on sequences of commits. It works on sets of commits. It’s right there in the documentation.⁽²⁾

History-traversing commands, such as git log, operate on a set of commits, not just a single commit.

For these commands, specifying a single revision, using the notation described in the previous section, means the set of commits reachable from the given commit.

A commit’s reachable set is the commit itself and the commits in its ancestry chain.

So master..topic means ^master topic, which means:

All the commits on topic: C1---C2---C3---C4
Excluding all the commits on master: C1---C2---C5---C6
Which leaves: C3---C4

$ git log --oneline --graph --decorate master..topic
* 703d475 (HEAD -> topic) C4
* 3ffdcab C3

Not including the master commit itself. ↩︎
If you’re like me, you learned Git by looking at examples and memorizing a handful of Git commands that you use as magic incantations. This post is part of my trying to understand what these magic spells mean. ↩︎

Implementing categories

2019-01-20T00:00:00Z

I want there to be Categories in Eleventy to organize articles into broad domains.⁽¹⁾

The idea is that all articles about books will go into the Culture category, articles about tech go into the Tech category, and so on.

An article does not have to specify a category.
An article can belong to only one category.
Category names are Capitalized by convention.

Tags, on the other hand, can be in any category. A weird book and some weird code would be in different categories, but they could both be tagged weird.

How we’ll use them

Let’s look at how we’ll use categories:

How to specify the category for an article
How to get an article’s category in a template
How to work with all of the articles in the same category

Specifying the category

Use the category property like this to specify the category an article belongs to:

---
date: 10/30/2018
title: Loomings
category: Tech
tags:
  - tools
  - git
  - eleventy
---

Using the category in a template

In a template, refer to the category property in the usual way:

<a href="/categories/Tech">Tech</a>

Working with articles in the same category

We can work with articles in the same category by creating a categories collection.⁽²⁾ To list all of the articles in the Tech category, you could do it this way:

<ul>
  {%- for article in collections.categories["Tech"] -%}
    <li>{{ article.data.title }}</li>
  {%- endfor -%}
</ul>

Just as collections is an object that has a property for each tag, so collections.categories has a property for each category. Each property refers to an array of articles. It looks something like this:

collections: {
  all: [ items ],
  categories: {
    Culture: [ items ],
    Life: [ items ],
    Thinking: [ items ]
  }
}

The implementation

We want:

a list of categories
an object that contains a property for each category, and each property is a list of articles for that category

Creating a list of categories

To get the list of categories, we iterate over all of the rendered templates. This code creates a collection called categoryList that contains the names of all the categories.

getCatList = function(collection) {
  let catSet = new Set()

  collection.getAllSorted().forEach(item =>
        typeof item.data.category === "string"
    &&  catSet.add(item.data.category))

  return [...catSet]
}

eleventyConfig.addCollection("categoryList", getCatList)

Creating a list of articles for each category

To get lists of each article in a category, we want to create an object that has a property for each category, and each property contains a list of articles of that category. In other words, we want to end up with an object that looks like this:

categories {
  Culture: [article_1, article_4],
  Tech: [article_3],
  Life: [article_1, article_3]
}

We can use the makeCategories() function as a callback to addCollection() to create this object. We iterate over each item that has a category property in its front matter and add it to the list for that category:⁽³⁾

makeCategories = function(collection) {
  let categories = {}

    // Every rendered page

  collection.getAllSorted().forEach(item => {
    let category = item.data.category

      // Ignore the ones without a category

    if (typeof category !== "string")
      return

    if (Array.isArray(categories[category]))
        //  category array exists? Just push
      categories[category].push(item)
    else
        //  Otherwise create it and
        //  make `item` the first, uh, item.
      categories[category] = [item]
  })

  return categories
}

Since we want to call our collection of categories categories, we’d build it like this:

addCollection("categories", makeCategories)

So now we have a way to make a collection that has collections of its own. I use it to segregate my posts into unique buckets.

That’s what I say now. The original impetus for this was to figure out how collections work. ↩︎
You can use any name you like. I happen to like “categories”. ↩︎
This if (Array.isArray(categories[category])) thing is really stupid. Isn’t there a way to push to an array, creating it if it doesn’t exist. ↩︎

Working with collections

2019-01-15T00:00:00Z

This post was written in 2019 for Eleventy 0.9.0. The general concepts are still valid, but the details may have changed.

Eleventy uses collections to group posts according to various criteria. A collection might consist of articles in a series. Another collection could be of posts about books. A third could be all the posts in a particular directory.

Eleventy gives you two ways to create collections:

implicitly, with tags in the front matter
explicitly, with addCollection()

Tag-based collections

Pages that share a tag are in the same collection. A template with the following front matter would generate pages in the collections books and reviews.

---
title: Finding Oz
category: Culture
tags:
- books
- reviews
---
. . .

Within a template collections are accessed by name as properties of the global collections object.

<p>
  The title of this page is:
  {{ collections.books[0].data.title }}
</p>

Collections are usually used in loops to iterate over each item in the collection.

{% for post in collections.books %}
  {{ post.data.title }}
  {{ post.url }}
  {{ post.data.category }}
  {{ post.data.tags }}
  {{ post.date }}
{% endfor %}

The collections object itself looks like this:

{
  "all": [...],
  "nav": [...],
  "books": [
    {
      "inputPath": "./src/articles/finding-oz.md",
      "outputPath": "_site/articles/finding-oz/index.html",
      "fileSlug": "finding-oz",
      "data": {...},
      "date": "2009-08-07T13:52:12.000Z",
      "url": "/articles/finding-oz/",
      "templateContent": "<p>As with most books ... much about The Wizard of Oz</li>\n</ul>\n",
      "template": {...}
    },
    ...
  ],
  "programming": [...],
}

Each property is an array of collection item objects (the doc also calls them template objects). The special collection all is an array of all of the page objects that Eleventy generates.

Property	Description
`inputPath`	Path to this file including the `input` directory. `./src/articles/finding-oz.md`
`outputPath`	Path to the rendered file. `articles/finding-oz/index.html`
`fileSlug`	Short name from the file name. There are rules. `finding-oz`
`data`	Data from the front matter of the rendered page. The global variables available to each page.
`date`	The date of this file in UTC. There are rules. `2009-08-07T13:52:12.000Z`
`url`	Path to this content. Doesn’t include protocol or host. `/articles/finding-oz/`
`templateContent`	The rendered content, not including any layout wrappers. `<p>As with most books … much about The Wizard of Oz</p>`
`template`	All sorts of data parsed out of the template. Things like the Eleventy configuration, markdown engine setup, and lots of stuff we probably shouldn’t rely on.

!!! Implementation: How a tag becomes a collection

getTaggedCollectionsData() is the function that turns tags into collections.

async getTaggedCollectionsData() {
  let collections = {};
  collections.all = this.createTemplateMapCopy(
    this.collection.getAllSorted()
  );
  debug(`Collection: collections.all size: ${collections.all.length}`);

  let tags = this.getAllTags();
  for (let tag of tags) {
    collections[tag] = this.createTemplateMapCopy(
      this.collection.getFilteredByTag(tag)
    );
    debug(`Collection: collections.${tag} size: ${collections[tag].length}`);
  }
  return collections;
}

getTaggedCollectionsData() gets called in TemplateMap.cache() which is where Eleventy builds the collections. !!!

Custom Collections

In addition to the collections built from tags, you can use addCollection() in your .eleventy.js configuration file to create your own collections.

For example, this is how to create a collection called articles made up of pages generated from templates in the directory src/articles/:

eleventyConfig.addCollection("articles",
  collection => collection
    .getAllSorted()
    .filter(item => item.url
                 && ! item.inputPath.includes('index.njk')
                 && item.inputPath.startsWith('./src/articles/')))

addCollection() takes two arguments:⁽¹⁾

the name of the collection (a string)
a function that takes a collection as an argument.

addCollection(name, callback) {
  name = this.getNamespacedName(name);

  if (this.collections[name]) {
    throw new UserConfigError(
      `config.addCollection(${name}) already exists. Try a different name for your collection.`
    );
  }

  this.collections[name] = callback;
}

You might think that the collection parameter is an array of template objects like the tag-based collections object. Instead, this parameter is an instance of a TemplateCollection, which is derived from Sortable, and looks like this:

{
  "items": [
    { ... },
    . . .
    { ... }
  ],
  "sortFunctionStringMap": { ... },
  "sortAscending": true,
  "sortNumeric": false
}

Its items property is an array of all the template objects. It’s the same as collections.all. You don’t want to access the items directly like this: collection.item[n]. Instead use the following methods to get the items.

Method	Description
`getAll()`	Gets all of the items in arbitrary order.
`getAllSorted()`	Gets all of the items in order.
`getFilteredByTag(tagName)`	Get all of the items with a specific tag.
`getFilteredByGlob(glob)`	Gets all of the items whose `inputPath` matches one or more glob patterns.

The items are almost the same as the ones in the tag-based collections. In tag-based collections, items have templateContent. In addCollection() collections, items have _pages. I don’t know why.

You can use addCollection() to create collections of pages. Since Eleventy 0.5.3, you can use it to create collections or arbitrary objects.

For instance, this is how you’d make a collection that consists of an array of all the category properties:

module.exports = function(collection) {
  let catSet = new Set()

  collection.getAllSorted().forEach(item =>
        typeof item.data.category === "string"
    &&  catSet.add(item.data.category))

  return [...catSet]
};

!!! Implementation: How custom collections get built

getUserConfigCollectionsData() is the function that calls addCollection()'s callback.

async getUserConfigCollectionsData() {
  let collections = {};
  let configCollections =
    this.configCollections || eleventyConfig.getCollections();
  for (let name in configCollections) {
    let ret = configCollections[name](this.collection);

    // work with arrays and strings returned from UserConfig.addCollection
    if (
      Array.isArray(ret) &&
      ret.length &&
      ret[0].inputPath &&
      ret[0].outputPath
    ) {
      collections[name] = this.createTemplateMapCopy(ret);
    } else {
      collections[name] = ret;
    }

    debug(
      `Collection: collections.${name} size: ${collections[name].length}`
    );
  }
  return collections;
}

getUserConfigCollectionsData() gets called in TemplateMap.cache() which is where Eleventy builds the collections. !!!

addCollection() doesn’t actually do anything other than to associate the collection-building function with the collection name. The collection-building function itself is called later in getUserConfigCollectionsData(). ↩︎