Philipe Fatio

Git aliases supporting main and master

2022-06-23T00:00:00Z

More and more projects are moving or have moved from a default master branch to one named main. I deal with repos that use both. This means Git aliases that assume master or main break depending on the repo. With the help of a certain Git config these aliases can be made agnostic to the default branch.

I use Git aliases quite extensively. Some of the aliases involve the default branch. The one I use the most is git com which was defined as follows:

[alias]
  com = switch master

(com used to denote CheckOut Master before git switch existed.)

Once I’ve started working on repos that use main as the default branch, git com no longer worked:

$ git com
fatal: invalid reference: master

Git 2.28 introduced a new config called init.defaultBranch alongside a new warning when initializing a new repo:

$ git init
hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint:
hint:   git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint:   git branch -m <name>
Initialized empty Git repository in /Users/phil/foo/.git/

By now you might have come across this warning and set init.defaultBranch globally to whichever value you prefer, e.g. main:

git config --global init.defaultBranch main

We can now change the alias to a shell script alias to (ab)use this value:

[alias]
  com = !git switch "$(git config init.defaultBranch)"

This will read out the config from the repo and fall back to the global value if none is set. Because the repo doesn’t define init.defaultBranch, it’ll return the global value main.

Once we find ourselves in a new repo that doesn’t have a main branch and instead uses a master branch, the command will fail:

$ git com
fatal: invalid reference: main

That makes sense, the global config is set to main, but the repo uses master as the default branch¹. All we need to do now is to set the config init.defaultBranch to master for the current repo, i.e. without the --global flag:

git config init.defaultBranch master

Repeating the command now succeeds:

$ git com
Switched to branch 'master'

This approach has worked well for me. When working on a new repo that deviates from my preferred initial branch, as soon as I hit the first error related to the default branch, I simply run one command that is already in my shell history and all my aliases work again.

If you liked this post, you might also like my other post Configuring Git for work.

Git doesn’t really have a concept of a default branch except in the exact moment of initializing a new repo where the global config init.defaultBranch is respected. main or master aren’t in any way special; they’re just branches like any other. ↩

Grep one-liners as CI tasks

2022-01-08T00:00:00Z

The ubiquitous grep utility can go a long way in enforcing simple rules in a codebase. Plenty of options and readable output combined with a smart exit status allow for simple one-liners in your continuous integration setup that are easy to write and maintain.

The other day my team encountered an issue that we wanted to prevent via a CI task. We needed a quick way to ensure that our automated Android release builds would not contain any missing translations. These are typically stored in strings.xml files using <string> XML tags.

This grep command was all we needed to quickly¹ find such offenses:

$ grep --recursive --line-number --include=strings.xml '>\(""\| *\)</string>$'

The output reads rather nicely and tells us precisely where the offenses are, also thanks to the additional --line-number option:

./app/src/main/res/values/strings.xml:23:    <string name="some_key"></string>
./app/src/main/res/values-fr/strings.xml:147:    <string name="another_key">""</string>

A cool thing about grep is that it has a smart exit status. From GNU grep’s man page:

Normally the exit status is 0 if a line is selected, 1 if no lines were selected, and 2 if an error occurred.

Thus, as long as we have offenses we get an exit status 0, denoting success. Once we fix the offenses no lines will be matched by grep and the exit status will be 1, denoting that it was unsuccessful.

Since we want to fail the CI task in our grep one-liner, we need to invert this exit status. Thus, when no offenses are found, we need to exit with 0, otherwise with 1.

Shell script allows a pipeline of one or more commands such as cmdA or cmdA | cmdB to be prefixed with a ! (followed by a space), i.e. ! cmdA or ! cmdA | cmdB. This alters the exit status as described in the Shell Command Language reference:

If the pipeline does not begin with the ! reserved word, the exit status shall be the exit status of the last command specified in the pipeline. Otherwise, the exit status shall be the logical NOT of the exit status of the last command. That is, if the last command returns zero, the exit status shall be 1; if the last command returns greater than zero, the exit status shall be zero.

Thus, to get the desired inverted exit status for our CI task we just need to prefix grep with !.

If we want to additionally print a success message when no offenses where found, we can do so with an echo "message" which we combine with a logical && operator.

Equipped with this knowledge, we conclude with a generic one-liner that fails the task in case offenses are found and prints a success message otherwise:

! grep [option...] [patterns] [file...] && echo "No offenses found"

I personally prefer ripgrep as it is much faster than grep, but usually that is not available on CI machines. ↩

Configuring Git for Work

2020-11-17T00:00:00Z

You can override your globally configured email inside individual repositories, allowing you to use your work email for work-related repos. Setting this up for each repo—and remembering to do so—is cumbersome. Luckily, there is an easier way to accomplish this for all repos within a certain directory.

One of the first things you did when you set up Git was to configure your name and email:

$ git config --global user.name "Jane Doe"
$ git config --global user.email jane@mail.com

The above commands added the following lines to your global Git configuration file ~/.gitconfig:

[user]
	name = Jane Doe
	email = jane@mail.com

Each repository also has its own Git configuration located at .git/config. Configs in the local file take precedence over the global configs.

You can set configs in .git/config manually or by passing the --local flag to git config. Thus, if I want to use my work email in a specific repo, I need to set it as follows:

$ git config --local user.email doe@acme.org

If you want to do this for all work repos, it gets a bit cumbersome. Above all, it’s easy to forget to do this for repos that you’ll clone or create in the future.

Fortunately, Git has a more scalable approach to this problem. You can conditionally include further Git config files based on the directory of a Git repo.

Let’s assume that all my work-related repos are inside the folder ~/Documents/Acme/repos/.

First, I’ll create a separate Git config file ~/.gitconfig-work that contains my work-related overrides:

[user]
	email = doe@acme.org

Then, I include this file from my global Git config file in ~/.gitconfig:

[includeIf "gitdir:~/Documents/Acme/repos"]
	path = .gitconfig-work

It’s important to place above snippet at the end of your ~/.gitconfig file because, according to the documentation on git-config:

The contents of the included file are inserted immediately, as if they had been found at the location of the include directive.

If we were to restructure our work directory, e.g. by changing Acme to acme or by moving the repositories somewhere else, such as to ~/repos/acme/, the include directive would no longer apply. My newly created commits would now use my globally defined private email rather than my work email. Most likely, I wouldn’t even notice.

To prevent this from happening, we can generalize the path used in the include directive above. First, we can use gitdir/i to perform the matching case-insensitively. Further, there are a few assumptions around the path that can help us. From the docs:

If the pattern does not start with either ~/, ./ or /, **/ will be automatically prepended. For example, the pattern foo/bar becomes **/foo/bar and would match /any/path/to/foo/bar.

If the pattern ends with /, ** will be automatically added. For example, the pattern foo/ becomes foo/**. In other words, it matches “foo” and everything inside, recursively.

Equipped with this knowledge, we can generalize the include directive so that it applies to any Git repository that is nested within a folder named after my company—case-insensitively, mind you:

[includeIf "gitdir/i:acme/"]
	path = .gitconfig-work

To verify that this is working, I can look up the resolved config value in a specific repo:

$ cd ~/repos/private/my-project
$ git config user.email
jane@mail.com

$ cd ~/Documents/Acme/repos/website
$ git config user.email
doe@acme.org

I encourage you to check out the git-config manual (git help config). You’ll find some interesting things in there. For instance, an include directive can be conditional on the branch you’re currently on.

Is There a Better Way?

2020-02-02T00:00:00Z

A lot of the tasks we perform on a computer are repetitive and come with a cognitive load. Minimizing this repetitiveness helps us stay focused and accomplish our tasks quicker. As developers, our main tools to get the job done are the OS, the browser, our editor of choice, and the terminal. Investing in those and molding them to your needs pays off.

As someone who spends most of their workday in front of a computer, I like to reduce visual clutter and to optimize workflows. For that reason, I’ve customized my computer and tools to suit me, from keyboard shortcuts, to simplifying the UI, up to customizing touchpad gestures.

This is the result of a constant, but passive, pursuit over the years for doing things in an easier, quicker, and mentally less taxing way. When repeating a task for a few times that I find too tedious, I tell myself: there must be a better way!

When observing other computer users, I’m often astounded how little they deviate from the typical point-and-click mode of using a computer—especially for peer developers. This goes from the simplest action such as switching apps, where they reach for the mouse to click on an icon in the dock, to more advanced tasks such as editing and navigating text where they only ever change or jump one character at a time.

In the following I’ll list a few examples I’ve observed others do over the years and how to—I believe—do it better. I understand that these suggestions might be opinionated and I don’t expect you to agree with me. Nonetheless, I hope this will motivate you to refine your workflow and hone your skills in using your tools.

macOS
Web Browsing
- The Power of Bookmarks
- Predictable URLs
Text Editors
- Jump to File
- Line-wise Editing
Terminal
Touch-typing

macOS

I’m a mac user and thus these examples and tips are specific to macOS. Nonetheless, the ideas behind them may apply to other OSs as well.

I’m always surprised when I see a fellow developer grab their mouse to click on one of the typical menu items for which there is a keyboard shortcut. New File (⌘N), Save (⌘S), New Tab (⌘T), Close (⌘W), Quit (⌘Q), Preferences (⌘,), these are all typically bound to the same keyboard shortcut across apps.

There’s no excuse not to memorize them. The menu even shows us the shortcut for the item:

If you want to get more out of the menu, macOS has a few tricks up its sleeve.

Sometimes you forget the shortcut for a particular menu item. Maybe you even forgot where that particular menu item is or you don’t even know whether a menu item for doing a certain action exists. This is where the Help menu comes in handy.

Suppose I’m in a graphics editor and I want to change a mask to use its alpha channel for masking. Opening the Help menu item and typing alpha will show me where the menu item is. I can also launch it conveniently from there by hitting return.

You can focus this search field in the Help menu item with ⇧⌘?, effectively turning it into a mini launcher for menu items.

If you find yourself using the same menu item often, but that specific item doesn’t have a keyboard shortcut assigned to it, you can assign a custom one. This can be done in System Preferences in the Keyboard pane under the Shortcuts tab. Select App Shortcuts in the list and press the plus button. Now you can select the app, enter the menu item title for which you want to add a shortcut, and finally specify the shortcut. That menu item will now show your custom shortcut.

Here you can find an official and extensive list of generic macOS keyboard shortcut.

Switching Apps and Windows

One way of switching between windows and apps that I’ve seen people do surprisingly often is to move the topmost window slightly to the side in order to reach the window behind. The next best way is to click on an icon in the Dock, which brings to front the desired app, but not necessarily the desired window in case the app has multiple.

When I started using a Mac, I was a big fan of Exposé and Hot Corners. I still have my top right screen corner set to trigger Exposé for all apps and the top left corner set to Exposé for the current app. When I’m in mouse mode, that’s a great way to switch apps and windows.

Mostly I’m in keyboard mode though where I use ⌘⇥, i.e. Command-Tab, to switch apps. If you keep Command pressed after hitting Tab, the app switcher will stay visible:

Pressing Tab again moves the selection to the next app. Releasing Command will bring that app to foreground.

To move the selection to the left, hit the key ` (backtick) key located above Tab (or use the left arrow).

While the switcher is open, you can also quit or hide the highlighted app by hitting Q or H, respectively.

A key feature of the app switcher is that the apps are ordered by recency. Let’s say you’re composing an email in Mail. You might need to look something up in Safari so you hold Command followed by the number of Tab strokes required to select Safari. Mail is now located after Safari in the app switcher. Thus, to jump back to Mail, a single ⌘⇥ will take you there. This is so quick that the switcher won’t even show. Now Safari will be in second position, such that repeated ⌘⇥ strokes cause you to cycle between Mail and Safari.

Switching between windows of the current app is similar. In Mail you might need to switch between the compose window and the mailbox window. You can cycle between the windows using ⌘` (⇧⌘` in the reverse direction).

Window Manager

Fiddling with windows to move or resize them is another thing where I’ve told myself a long time ago that there must be a better way. The process of grabbing a window, moving it to a corner of the screen then dragging its opposite corner to resize it in order to maximize a window is as cumbersome as it can get. Another use case I see often is placing two windows side by side.

This is where a window manager comes in handy, which conveniently turns these manipulations into single clicks or key strokes. No more fiddling with windows and their edges.

There’s quite a few such window managers available for macOS. I started with SizeUp ten years ago, which worked great, but soon after switched to Slate, which offers more customizability and has some additional features. Slate barely has any UI, but is highly customizable using a text based config file (here’s mine in case you’re curious).

The typical things that I do with a window:

maximize with ⌃⌥⌘M
center with ⌃⌥⌘C, which causes the window to use ⅔ of the screen width and full screen height, useful for websites that don’t work well when too wide
resize to the left half of the screen with ⌃⌥⌘H
resize to the right half of the screen with ⌃⌥⌘L
resize to the lower half of the screen with ⌃⌥⌘J
resize to the upper half of the screen with ⌃⌥⌘K
throw the window to the next screen with ⌃⌥⌘N when connected to more than one monitor

Hiding Unused UI

When looking at other people’s screen, I often wonder if the buttons present in the UI of apps they use are ever pressed by them. Apps by default come with a toolbar full of buttons, some more useful than others. In my opinion these clutter the UI unnecessarily, especially if you never press them.

For that reason, I like to customize the UI of the apps I use most. One such app is Mail. Except for browsing messages, I do most of the actions using keyboard shortcuts. For that reason, I don’t need any of the buttons in the toolbar that are shown by default.

I have removed every item in the toolbar except for the search field. Since the search field is only used occasionally, I also hide the toolbar entirely. I can focus the search field by pressing ⌥⌘F, which will reveal the toolbar temporarily until I clear the search.

The compose window is similar. The default comes with plenty of buttons that I don’t need.

All I want is an experience reduced to the max so I can focus on the message.

If I want to make something bold or italic, I hit ⌘B or ⌘I, respectively (these pretty much work globally on macOS). If I need a bullet list or a numbered list, I have my custom keyboard shortcuts ⇧⌘B and ⇧⌘1 for the respective menu items (see section above on how to add custom shortcuts).

Once I’m ready to send the message off, I hit ⇧⌘D (D as in deliver).

Cursor Movement and Text Selection

Countless times I’ve noticed that people don’t realize that there are more advanced ways to move the cursor in a text field or to select text than doing so character by character. It’s almost agonizing to see someone move their cursor by holding down ← or → for several seconds (if only they’d at least increase the key repeat rate) or to see them trying to select a word or range of words and missing a character or selecting one to many.

Selecting a single word is as simple as double-clicking it. To select a range of words, select either the first or last word by double-clicking it, then click the word on the other end of the range while holding down Shift. The following video demonstrates this:

As you see, no need for surgical precision with your mouse.

If you want to select an entire paragraph rather than a range of words, simply triple click on the paragraph.

Similarly, moving your cursor in a text field can be done quicker than character by character. While holding down Option you can press ← and → to move word-wise. To move to the beginning or end of the line, use ⌘← and ⌘→. The up and down arrows can also be used: ⌥↑ and ⌥↓ allow you to move by paragraph while ⌘↑ and ⌘↓ move the cursor to the very beginning and end of the field, respectively.

The above shortcuts can be combined with Shift to select text rather than just move the cursor.

Option and Command can also be combined with Backspace (i.e. delete to the left) and Delete (i.e. delete to the right): ⌥⌫ and ⌥⌦ delete the word to the left and right, respectively; ⌘⌫ and ⌘⌦ delete from the cursor position to the beginning and end of the line, respectively.

These days I prefer the Emacs bindings that also work globally on macOS. The reason is that I use these extensively in the terminal (as described later) where above shortcuts don’t work. Additionally, they allow me to stay on the home row.

The shortcuts are:

⌃B (back) to move left instead of ←
⌃F (forward) to move right instead of →
⌃P (previous) to move up instead of ↑
⌃N (next) to move down instead of ↓
⌃⌥B to move left word-wise instead of ⌥←
⌃⌥F to move right word-wise instead of ⌥→
⌃A to move to the beginning of the line (in contrast to ⌘← it uses hard wraps as anchors, not soft wraps)
⌃E to move to the end of the line (in contrast to ⌘→ it uses hard wraps as anchors, not soft wraps)
⌃H to delete to the left instead of ⌫
⌃D to delete to the right instead of ⌦

Clipboard History

Quite often the need arises to copy two or more bits of text to another place. Unfortunately, the clipboard only holds one copied value at a time. Thus, you need to switch a few times between the app containing the bits to be copied and the app where you need to paste the information until you’ve transferred the data.

This is where a clipboard history comes in handy. Instead of switching back and forth, copy the relevant parts, switch to the destination app, and retrieve the items from the clipboard history.

I use LaunchBar as an app launcher—basically a Spotlight on steroids. It comes with many useful features, including a clipboard history. Here’s a short demo on how a clipboard history can make your life easier:

A clipboard history is so essential to my workflow today that I can’t imagine how I worked without one for so many years. I recommend it to colleagues whenever I see them copy-pasting multiple times between two apps, and that happens quite often.

Web Browsing

The Power of Bookmarks

Navigating is the perfect example for reducing the number of steps to reach your goal. Countless times I’ve seen developers open github.com just to then search for a repository somewhere in a list, navigate to it, and then switching to the repository’s issues.

I used to be that person until I stopped for a second to realize how tedious this is and how long it was taking me. A simple bookmark could take me there directly. Placing a bookmark in your browser’s new tab view gets you a long way.

I’ve since taken this to another level. Now I have hierarchies of bookmarks for many services I use. For GitHub e.g. that would mean a GitHub folder with the pages and repos that I use regularly:

GitHub
- Assigned Issues
- My Pull Requests
- My Issues
- Review Requests
- Projects
- organization/repo
  - Home
  - Issues
  - New Issue
  - Pull Requests
- …

I do the same for other services such as Basecamp or Trello.

With LaunchBar I can quickly open any bookmark without even switching to the browser first. The hierarchy allows me to drill down to the bookmark I’m looking for in case I don’t remember its title, which is useful for pages that I access less often.

It’s like navigating without waiting for the intermediate pages to load and without the clutter.

Predictable URLs

Navigating to URLs with predictable patterns is another area where a launcher can speed up things significantly. Let’s say you look up third party dependencies quite often. I do that e.g. for the Ruby language where a package is called a gem. Instead of opening my browser and googling rails gem, I’ve set up a search pattern in LaunchBar. I trigger LaunchBar, search for the RubyGems action by typing gem, type in rails and hit return, and https://rubygems.org/gems/rails opens in the browser.

This also works great for the search functionality of any website.

Text Editors

Many text editors and IDEs share a few fundamental features that are often even bound to the same keyboard shortcuts. I’d like to highlight two such features here that I’ve often seen neglected by other developers.

Personally, I used to be a TextMate user until I switched to Vim about eight years ago. With TextMate I did learn quite a lot of great features that, if I’m not mistaken, were copied or at least inspired similar features in other editors. Because of this and the fact that I still know most shortcuts by heart, I quickly find myself at home for basic editing and navigation in other editors.

Jump to File

Some developers like to navigate to files by looking them up in the editor’s file tree. I get that some people have a visual memory. But when all you want is to jump to the file app/models/user.rb, why would you look for a folder, expand it, look for the next folder, expand it, and finally look for the file user.rb when you can jump directly to it with a few key strokes?

This is where TextMate’s Open Quickly…, bound to ⌘T, really shines. If I’m not mistaken, this also works in Sublime Text and Atom. Type user and hit return and you’re in that file. If there are multiple matching files, type a few characters more or select the correct one in the list.

The search is typically fuzzy, meaning you don’t have to type all the characters in the sequence as they appear in the path name. Depending on how the fuzzy matcher works, you might be able to type less characters. E.g. if a file is called user_profile_controller.js, the initial character of each word, i.e. upc, might be enough to get this file as the top matching result.

Other fuzzy matchers, e.g. fzf, allow you to refine your search by typing a space and more characters, effectively filtering the obtained list. For instance, let’s say you type user and the following list appears:

tests/user_test.rb
lib/user.rb

If you append another word such that your search now says user lib, the list will be narrowed down to just lib/user.rb. The great thing about this is that it doesn’t have to be in the order that the words appear in the path (notice how lib comes before user in the path).

Jumping to a file is just the beginning. Once this is your default way of moving around, you might want to start looking at jumping directly to symbols (aka tags), e.g. classes and functions.

Line-wise Editing

Another concept that I learned to appreciate in TextMate—and is omnipresent in Vim—is line-wise operations. I’d claim that most developers don’t know the definition of a line.

A line is everything from the left edge of the text area (not where the non-whitespace starts) all the way to the end of the text including the newline.

When I observe people moving around lines of code, this lack of understanding results in plenty of fiddling with whitespace, like dramatized in this video:

Granted, this video shows a simple text editor. Most editors anicipate what you’re trying to accomplish by indenting your code and more. Still, from my experience there’s often some manual clean up needed.

On the other hand, if you use line-wise selection by triple clicking, you can cut and paste that line much easier:

Some editors also allow you to select an entire line with a keyboard shortcut so you don’t have to reach for the mouse. Also, there’s often a shortcut to move one or multiple lines around without cut and paste.

Terminal

For some, the terminal is their primary tool to get work done—like me. Others avoid it and prefer a GUI whenever possible. Even then, probably you still have to use it occasionally for certain tasks.

Thus, why not invest a bit in this tool to make your life easier?

Note that in this section I’ll be using the Emacs-style notation for keyboard shortcuts. To quote from Bash’s manual:

Control keys are denoted by C-key, e.g., C-n means Control-N. Similarly, meta keys are denoted by M-key, so M-x means Meta-X.

When I see others use the terminal, most move around the command line character by character. It certainly isn’t obvious how to move the cursor around other than using just the left and right keys. Often the person at least knows C-a and C-e to jump to the beginning and end of the line, so they jump to the closest end and then move from there to the place where they want to edit the line.

There are plenty of keyboard shortcuts that will make this so much easier. In fact, these shortcuts work pretty much on every command line, i.e. in your shell as well as in REPLs.

GNU Readline is what powers these interactive command lines. Because of that, you only need to learn the basic commands once in order to use them in (almost) all shells.

Here’s a short list of the most important ones (you’ll notice that they’re very similar to the shortcuts I’ve shown in Cursor Movement and Text Selection):

C-a: move to start of line
C-e: move to end of line
C-b: move one character to the left (same as left arrow, but without leaving the home row)
C-f: move one character to the right (same as right arrow)
M-b: move one word to the left
M-f: move one word to the right
M-DEL: delete word to the left
M-d: delete word to the right
C-k: delete to the end of the line
C-u: delete to the beginning of the line
M-.: retrieve the last argument of the last run command

In order to leverage the shortcuts that use the Meta key, such as M-b, you probably need to configure your terminal emulator to use the Alt key as Meta. In macOS’s Terminal app that setting is located here:

If you happen to be an iTerm user, it offers the option to map the left or right Alt key. This has the benefit that you can still use the other for typing special characters. Make sure to choose Esc+ rather than Meta:

I encourage you to explore these shortcuts. There’s many more that also interact with Readline’s own clipboard, the so-called kill-ring, allowing you to move arguments around without having to select and copy them first. Other shortcuts for instance allow you to change the casing of a word.

The Wikipedia page on GNU Readline has an extensive list of shortcuts. I also recommend this cheat sheet.

Touch-typing

I believe that touch-typing is a skill absolutely worth learning if a computer is your main work tool. Hunt-and-peck might get the job done and you might even be fast at it. Heck, you might even be able to do it without looking down at your keyboard. Though from my experience while observing other developers that don’t touch-type, the error rate is quite high, especially when not looking at your keyboard.

I had taken a touch-typing class in high school, but it didn’t stick. There was a competition among mostly male students to finish the exercises as quickly as possible. Of course we’d all hunt-and-peck to win.

When I started my first day job as a developer, I realized that I needed to take typing seriously and force myself to learn to touch-type, even if that meant being slower initially.

I used a free app to learn the basics. From there, I simply forced myself not to look. If I didn’t remember where a key was, I could look down. Yes, I was slow as heck in the beginning, but it totally paid out. My wife did the same a few years ago approaching her thirties, so I’m sure it’s never too late.

One might argue that at the end of the day you might not necessarily be faster at accomplishing your work by optimizing your workflow. Depending on the nature of your work, solving a problem in your head might be the lion’s share of your day, while its execution with your tools constitutes a fraction. By optimizing the execution, though, I’m confident that you can reduce the cognitive load of it, allowing you to keep focused on the underlying problem or idea, thus reducing the chance of distractions. That in itself is already worth it.

Therefore, I encourage you to stay curious about your workflow and tools. Try to notice patterns and then ask yourself: is there a better way? Google for what you’re trying to accomplish.

Further, invest in your tools. Occasionally read their docs and browse their menus and settings. That way I’ve come across features I didn’t know existed. Having them in the back of your head will cause you to go: wait a second, wasn’t there this feature that would accomplish what I’m doing, but much quicker?

And for those that say “I can’t memorize shortcuts or commands”, write them down on a piece of paper and leave them somewhere visible close to your screen. The act of writing them down might already cause you to memorize them. If not, next time you need that one shortcut, glance down. After a few times you’ll know it by heart.

I like to observe how others work and learn from their unique setups and workflows. If you have a tool or tip you’d like to share, I’d love to hear from you.

Loading Additional Ruby Gems in Development

2019-10-20T00:00:00Z

Have you ever found yourself temporarily adding a gem to your project’s Gemfile to leverage it during development? Maybe your project even has gems that some team members find indispensable during development, but mean nothing to others. Luckily, there’s a way to have your favorite gems available without permanently or temporarily adding them to the project’s Gemfile.

Recently at my company we were spring cleaning our app’s Gemfile. Over the years people have added gems to it that they heavily rely on during development, myself included.

I always use the Fuubar formatter for RSpec and greatly prefer it over the default formatter. Sporadically I might need to get a flame graph for a performance critical part of the app, so I temporarily add the Flamegraph gem. Other times I can’t wrap my head around Rails’ implicit i18n key resolution, so I quickly add my i18n-debug gem.

While doing this spring cleaning someone pointed out that there’s a way to use a different Gemfile locally that allows you to add additional gems. This sounded like the correct approach that would make everyone happy.

As it wasn’t straightforward to set this up and getting it to work correctly, especially in the context of a Rails app using Spring and Puma-dev or Pow, I wanted to document the necessary steps. Hopefully this comes in handy for someone else.

Setting up a Private Gemfile
Executing Commands Using Your Private Gemfile
Configuring Spring
Configuring Puma-dev or Pow

Setting up a Private Gemfile

In the root directory of a typical Ruby project you’ll have a Gemfile and a Gemfile.lock. The first step is creating a second Gemfile with a name of your choice, e.g. Gemfile.private. I first went with Gemfile.local as that’s what you find here and there on the internet, but I’ve found that Gemfile.local, Gemfile.lock, and Gemfile.local.lock are all too similar and ambiguous when using tab completion.

This file will evaluate the project’s Gemfile and list additional gems of your choice. Here’s how mine looks like:

eval_gemfile 'Gemfile'

gem 'fuubar'

gem 'stackprof'
gem 'flamegraph'

gem 'i18n-debug'

We now need to run bundle install while instructing Bundler to use this Gemfile instead.

Before doing so, it makes sense to use the Gemfile.lock as the starting point for version resolution. This ensures that we’ll get the same versions of the gems defined in Gemfile, especially if you’re using pessimistic version constraints.

$ cp Gemfile.lock Gemfile.private.lock

Now we can bundle install using Gemfile.private:

$ BUNDLE_GEMFILE=Gemfile.private bundle install

Because you’ll be using Gemfile.private during development, you’ll have to remember to do changes, which should be checked in, directly on the Gemfile and Gemfile.lock, e.g. when updating or adding a gem.

On the other hand, whenever Gemfile.lock was changed upstream, you’ll have to redo the copy and bundle install step for your private Gemfile in order for your Gemfile.private.lock to include those upstream changes.

I have written a Bundler plugin that takes care of this step whenever running bundle install. To install the plugin globally, run the following in a directory that doesn’t have a Gemfile:

$ bundle plugin install bundler-private_install

Executing Commands Using Your Private Gemfile

When running a command through Bundler, you’ll need to set the BUNDLE_GEMFILE environment variable for Bundler to load the gems specified in your private Gemfile.

$ BUNDLE_GEMFILE=Gemfile.private bundle exec foobar

You can also export BUNDLE_GEMFILE in your shell so you don’t have to repeat it for every command:

$ export BUNDLE_GEMFILE=Gemfile.private
$ bundle exec foobar

If you’re using Bundler binstubs, have a look at a binstub. You’ll notice at the top of a binstub that it supports BUNDLE_GEMFILE:

ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
  Pathname.new(__FILE__).realpath)

This means that your binstubs will pick up your private Gemfile:

$ BUNDLE_GEMFILE=Gemfile.private bin/rake

Rails binstubs are slightly different as they don’t load Bundler directly, but instead load config/boot.rb, which supports BUNDLE_GEMFILE as well. At the top of config/boot.rb you’ll see a similar snippet:

ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)

A few lines later, after having set BUNDLE_GEMFILE, it loads the Bundler setup.

If you’re working with Spring and a server such as Puma-dev or Pow, you’ll have to go through a few extra hoops described below.

Configuring Spring

When running commands that leverage a preloaded application through Spring, such as rails console or rspec, it will not pick up the BUNDLE_GEMFILE that’s set in the shell.

Luckily, Spring provides configuration hooks:

Spring will read ~/.spring.rb and config/spring.rb for custom settings. Note that ~/.spring.rb is loaded before bundler, but config/spring.rb is loaded after bundler.

Because we need BUNDLE_GEMFILE to be set before Bundler is loaded and because we want to do this config globally and not for every project where we want a private Gemfile, the ~/.spring.rb file is the right spot.

Add the following snippet to ~/.spring.rb that sets BUNDLE_GEMFILE if there is one (note that this file gets evaluated in your project’s root):

ENV['BUNDLE_GEMFILE'] = 'Gemfile.private' if File.exist?('Gemfile.private')

Now, whenever you’re working on an app that has a Gemfile.private, you’ll have your additional gems available inside Spring-powered commands.

Configuring Puma-dev or Pow

Similarly as for Spring, we need to configure Puma-dev or Pow to set BUNDLE_GEMFILE.

Puma-dev also features a set of config files according to the advanced configuration section of the docs:

Puma-dev supports loading environment variables before puma starts. It checks for the following files in this order:

~/.powconfig

.env

.powrc

.powenv

The ~/.powconfig file is exactly what we need. Puma-dev, dubbed “the emotional successor to pow”, simply uses the same file as Pow. In case you’re still using Pow, the relevant section of the manual is here.

Analogous to ~/.spring.rb, we set BUNDLE_GEMFILE in ~/.powconfig, which is a shell script:

[ -f Gemfile.private ] && export BUNDLE_GEMFILE=Gemfile.private

As for Spring, this file is evaluated in the root of the app being booted.

Remember to restart the app with touch tmp/restart.txt if it was running. After that, whenever Puma-dev boots an app, it’ll first set BUNDLE_GEMFILE if a private Gemfile exists.

I hope that this guide helped you in setting up your private Gemfile.

As a final tip, if you’re working on multiple projects and find yourself adding the same set of gems, you could have a global private Gemfile, e.g. at ~/Gemfile.private and simply link to that file in your project:

$ ln -s ~/Gemfile.private