Providing detailed command output in GitHub issues is hard: I want to be complete, but I don’t want to paste unreadable walls of text. Some commands have long output that is usually uninteresting (pip install), but which every once in a while has a useful clue. I want to include that output without making it hard to find the important stuff.

While working on an issue with coverage.py 5.0, I came up with a way to show commands and their output that I think works well.

I used GitHub’s <details> support to show the commands I ran with their output in collapsible sections. I like the way it came out: you can copy all the commands, or open a section to see what happened for the command you’re interested in.

The raw markdown looks like this:

<details>
<summary>cd meltano</summary>
</details>

<details>
<summary>pip install '.[dev]'</summary>

```
Processing /private/tmp/bug881a/meltano
Collecting aenum==2.1.2
  Using cached https://files.pythonhosted.org/packages/0d/46/5b6a6c13fee40f9dfaba84de1394bfe082c0c7d95952ba0ffbd56ce3a3f7/aenum-2.1.2-py3-none-any.whl
Collecting idna==2.7
  Using cached https://files.pythonhosted.org/packages/4b/2a/0276479a4b3caeb8a8c1af2f8e4355746a97fab05a372e4a2c6a6b876165/idna-2.7-py2.py3-none-any.whl
Collecting asn1crypto==0.24.0
  Using cached https://files.pythonhosted.org/packages/ea/cd/35485615f45f30a510576f1a56d1e0a7ad7bd8ab5ed7cdc600ef7cd06222/asn1crypto-0.24.0-py2.py3-none-any.whl
(etc)
```

</details>

(The GitHub renderer was very particular about the blank lines around the <details> and <summary> tags, so be sure to include them if you try this.)

Other people have done this: after I wrote this comment, one of the newer coverage.py issues used the same technique, but with <tt> in the summaries to make them look like commands, nice. There are a few manual steps to get that result, but I’ll be refining how to produce that style more conveniently from a terminal console.

Update (Jan 2022): I needed to do this again, so I wrote a small program to do it: twisty_console.py.