$ considered harmful

One of the most satisfying feelings in life is waking up at 5am, going to the kitchen to drink a glass of water while casually scrolling through Twitter on your phone and finding someone (on the Twitter feed, not in the kitchen) that is right on the internet*:

* Where right means: someone else is saying something you always thought of, but never quite found time/space/willpower/occasion to express to a wider audience or even to yourself.

Disclaimer

Let's begin with a disclaimer: this is a clear case of first world problem that really has no great meaning in the grand scheme of things, and the arguments against it are still valid. I just found it amusing to see I wasn't really the only one being mildly frustrated by it.

I also think that the discussion that ensued is interesting and worth reading.

Problem

When setting up a project you might need some setup and most of the times this involves running a handful of shell command.  An example:

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
$ pyenv install 3.7.6
$ pyenv local 3.7.6

Ok, now try copy pasting those 3 lines in one go... Chances are you will see as output something like this:

zsh: command not found: $

Isn't this irritating?

What does $ even mean

There are a few reasons why $ is prepended to every line of a shell command example:

• it indicates that indeed, what you are looking at is a command that is meant to be run in a shell
• It indicates that you need to run this command as a user, and not as root

Why you should not remove $

Some valid arguments in favour of keeping the $:

• You should never trust commands on the internet and blindly copy paste them

• You should communicate when to run a command a root (using #) and when not ($)

The case for removing $

• makes it harder to copy, especially multiline commands
• not everyone might be aware of # meaning "run as root"

In the  thread another user makes an great point

How to remove $

If you have read so far and sort of agree that we might be better off not including the $ in shell samples, here's a few ways to make it happen.

The easy way

Just don't type it! This applies to Github and pretty much all places where you have no control over how code samples are rendered. A post on Dev.to is one example.

So this

$ pyenv install 3.7.6

becomes

pyenv install 3.7.6

if a command is meant to be run as root prepend it with sudo

sudo apt-get install ubuntu-desktop  

The stylish way

If you have control over the rendering and you still like you readers to see the $, consider using CSS to remove it from the text that ends up in the clipboard when copying. In the thread, Twitter user @beccadottex shares a Codepen of how this can be done.

@theconfigurator shares another one here

Should you really stop using $?

As any other opinion based topic, there seems to be far from an agreement on the best practice around this, as the long thread on Twitter shows.

As for myself, I always found it redundant and pointless but funnily enough I found myself using it out of habit. From now on, I will purposefully keep the $ out of my docs.

/rant

• comic at the beginning is a ripoff of Xkcd's Duty Calls
• cover image is by Ryan Quintal.