Pull request descriptions

I used to leave pull request descriptions empty. "Let the code speak for itself" or "let the commits speak for themselves" are the perfect getaway from the extra work of documenting your thought process.

Recently, I've experienced that spending time on a good description is a worthwhile investment.

Read more

Derrick Reimer: 'Ship small, ship fast'

Timeless advice from Derrick Reimer:

Not all projects are inherently small, but you can always break them down into smaller chunks. […]

Each incremental task brought us one step closer to a functioning v1. By shipping these tiny branches to production as we go, we became increasingly confident in the “bones” of the feature. As soon as a slice of the project was ready to test, the whole team hammered on it in production – an effective way to tease out bugs and rough spots in the user experience.

Scan for todos in a git diff

When I'm working on a feature or refactor, I often leave @todo comments to remain in flow and deal with other points later.

I don't mind committing them to my feature branch, as long as I work them away before merging in.

On large branches, it can be easy to forget about that todo I left in there a few days ago.

class PodcastController
public function process(Podcast $podcast): void
// @todo Broadcast event to trigger webhooks
return $podcast;

Before I merge, I pipe git diff into a grep call to scan for changes that include @todo.

git --no-pager diff main..feature-branch | grep -i "^\+[^$]*@todo"
+ // @todo Broadcast event to trigger webhooks

If you want to double check your changes before comitting, you can use the same command with git diff HEAD.

git --no-pager diff HEAD | grep -i "^\+[^$]*@todo"

Pouring this in a bash function

Here's a quick bash function to scan for todos:

function todos() {
git --no-pager diff ${1:"HEAD"} | grep -i "^\+[^$]*@todo"

Use it without an argument to look for todos you haven't committed yet, or pass the revisions you want to compare between.

# Look at current changes
# Look for todos added between main and feature-branch
todos main..feature-branch

Leading slashes in .gitignore

This is a friendly reminder to keep leading slashes in mind in .gitignore files.

The other day, I pulled down a project and couldn't get the CSS to build because files were missing. It turned out another developer created a new resources/css/vendor directory to override styles for third-party components. A fine name, but vendor was ignored so they were quietly missing from the repository. We updated .gitignore to use /vendor instead and all was well.

# Ignores all vendor files
# Only ignores vendor at the project root

Leaner feature branches

In most projects, we use git flow to some extent — depending on the project and team size. This includes feature branches.

Feature branches (or sometimes called topic branches) are used to develop new features for the upcoming or a distant future release. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown at that point. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).

Working on a project with a lot of interdependencies between features with a bigger team comes with a new set of challenges dealing with git.

We've recently set up a new guideline: if it's not directly tied to your feature, don't put it in your feature branch.

Read more

Setting up a global .gitignore file

Reviewing pull requests, I often see contributors sneakily adding editor configuration to the repository's .gitignore file.

+ .vscode

If everyone would commit their environment-specific .gitignore rules, we'd have a long list to maintain! My repository doesn't care about your editor configuration.

There's a better solution to this: a personal, global .gitignore file for all your repositories. Here's how you can set one up.

Read more