Ultimately, I look to @amacneil to decide how he wants the documentation formatted for this project, but here are my two cents:

My first 1¢ - Prefixing command-line interface examples in documented with the shell prompt character is a very well understood, long-standing convention for formatting command-line interface examples. Rather than me doing a poor job of trying to describe the how's and why's, I recommend people read the Google developer documentation style guide's command-line syntax page, to provide context for what I write next.

Historically, the importance of including the prompt in the command-line interface documentation was to signal to the reader whether the command was expected to be executed as an unprivileged (non-root) user, indicated by the $ prompt, as opposed to commands that should be executed by the privileged (root) user, indicated by the '#' prompt.

In modern times, the best practice is to prefix privileged commands with sudo, but keep in mind that this kind of documentation was being written long before sudo existed, and the convention remains because not everyone uses sudo even today. Therefore, signaling the expectation of what user privilege should execute the command by including the prompt character serves the same purpose.

Ultimately, examples are convenient if and when they can be copied and pasted verbatim by the reader, but that should not be the expectation. Documentation serves to inform a wide range of readers, who are expected to adapt the information presented to their specific situation, of which there are too many to accommodate in the documentation, and would create more confusion by even trying to do so.

My second 1¢ - I personally find it frightening how comfortable users have gotten with the practice of blindly copying commands and executing them, sometimes even with privileged (root) contexts. If you truly are not concerned with this, and are simply looking to make copying and pasting commands from documentation more convenient, you could do this:

$ echo 'exec $@' > /usr/local/bin/\$
$ chmod +x /usr/local/bin/\$

This will create a command named $ which will execute a new command from its arguments, effectively making the $ a no-op—although, technically there's some tiny overhead, it's negligible in the context of an interactive shell session.

Once you've performed the two commands above, you can copy and paste this directly into your shell:

$ echo hello world
$ date

And, it will effectively ignore the leading $ that's pasted in.

Now, this is an absolutely horrible idea and I feel terrible even documenting such a recommendation, but if you've committed to just copying and pasting commands wholesale into your command prompt, you may as well do this as a quality-of-life improvement for copying and pasting commands from all conventional documentation that uses $ as the prompt character in examples. This way, you don't have to ask for changes to all the pre-existing documentation that you come across.

Unfortunately, the same trick cannot be done with # as that's already a shell metacharacter indicating the rest of the line should be treated as a comment, so any command-line documentation examples that follow the convention of prefixing privileged command examples with # will need to be copied without including the leading # prompt character.

...

There are my 2¢ on the matter.

As I wrote earlier, ultimately it's up to @amacneil, but it is my opinion and personal preference to reject this PR and any that propose the same change in the future.

But, there are certainly benefits of doing it the way this PR proposes, and perhaps it's time to change the well-established standard.

Thanks for initiating the discussion.

Thanks for the thoughts.

I generally agree with @dossy here, I think some of the updated examples in this PR are a lot less clear, especially when mixing shell commands and output. For example:

cat .env
DATABASE_URL="postgres://[email protected]:5432/myapp_development?sslmode=disable"

The correct solution would be for github to correctly disable copy paste of leading $ when copying shell.

I do see that this is a slight pain point when copying the install instructions though. These are also all one-liners and don't contain any stdout.

I therefore propose accepting the proposed changes to the "Installation" section, and rejecting the rest. Thoughts?

I therefore propose accepting the proposed changes to the "Installation" section, and rejecting the rest. Thoughts?

Stylistically, it makes me a bit sad, but pragmatically, this seems like the best compromise.

I do agree that removing the prompt character where the command and its output are combined in the same block reduces readability and clarity, and should be rejected.