Best practices for transcripts from a computer terminal

When using command-line computer utilities (like a shell or a database client), it is sometimes useful to e-mail a transcript of your session to other people, or to post a transcript to ​a public pastebin or a ticketing system.

This page attempts to document some suggestions for making sure that transcript is clear and useful.

Preserve as plaintext

some e-mail and web-based systems like to treat things as fancy markup. a transcript is basically plain text, and should remain as such. For example, when entering a transcript on this ticketing system, your transcript will be better-preserved and more readable if you prefix it with {{{ and put }}} after it concludes (the docs call this Preformatted Text).

Avoid linewrapping

If at all possible, try to preserve the format of you transcript without line-wrapping. Many popular webmail services enforce line-wrapping, limiting the text to 80 columns wide. This makes it hard for the people reading your e-mail to know what you actually saw. If your webmail service or mail user agent does this and you can't figure out how to make it stop, you could paste the transcript into a text file (also without linewrapping!) and attach it to your e-mail.

Include your prompt, and the command you ran!

You might think people are just interested in the output that the computer shows you. But they don't know what you ran to generate the output. They also don't know where you started from.

Most shell prompts give a clue about where you started from, so include them, along with the command that you actually ran.

Include the trailing prompt

It's also very useful to show people where the end of the computer's output is. You can do this easily by including the trailing prompt that you are returned to.

Include the return code

If you're using a shell (or other command-line interface that has return codes for each command), modify your shell prompt to include the return code if possible before generating your transcript. That adds an extra hint for your readers about what happened, and will be useful for you.

If you use bash as your shell, make sure there is a literal $? in the prompt someplace. For a one-off transcript, you can add the return code to the beginning of your prompt with:

export PS1='$? '$PS1

If you want this permanently, you can do it in ~/.bashrc, or wherever where the PS1 environment variable is described. So if your ~/.bashrc contains this line:

PS1='${debian_chroot:+($debian_chroot)}\u@\h:\w\$ '

you can change it by just adding a $? inside the single-quotes:

PS1='$? ${debian_chroot:+($debian_chroot)}\u@\h:\w\$ '

Example transcripts

Bad

(no bad examples at the moment -- if you have a nice bad example, feel free to add it!)

Good

0 dkg@pip:~$ time wget -O/dev/null http://nytimes.com
--2010-12-03 15:05:34--  http://nytimes.com/
Resolving nytimes.com... 199.239.136.200
Connecting to nytimes.com|199.239.136.200|:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://www.nytimes.com/ [following]
--2010-12-03 15:05:34--  http://www.nytimes.com/
Resolving www.nytimes.com... 199.239.136.200
Reusing existing connection to nytimes.com:80.
HTTP request sent, awaiting response... 200 OK
Length: unspecified [text/html]
Saving to: “/dev/null”

    [  <=>                                  ] 133,240      623K/s   in 0.2s    

2010-12-03 15:05:35 (623 KB/s) - “/dev/null” saved [133240]


real	0m0.298s
user	0m0.004s
sys	0m0.004s
0 dkg@pip:~$