Live-publish your commands and their output from a bash
shell to GitHub Pages.
The idea for this project was specifically for instructors teaching the Unix Shell and Git lessons in Software Carpentry workshops. Learners and helpers can review your commands even if they've already moved off the screen.
Before you begin:
- You'll need
gawk
(GNU awk) andgit
installed. - On Ubuntu/Debian, the default awk is mawk, so you'll need to install gawk.
sudo apt-get install gawk
- On Mac, you'll need to install gawk and a GNU version of sed. You can do this with Homebrew (gawk, gnu-sed), MacPorts (gawk, gsed), or Rudix (gawk, sed).
Download the setup_ssh_key.sh
script and create an ssh key for github (or you can do this manually if you prefer).
$ curl -O https://raw.githubusercontent.com/evanlinde/shell-transcript/master/setup_ssh_key.sh
$ bash setup_ssh_key.sh
Clone this repository to your own github account, then use GitHub's import tool to make a copy for your teaching session. I recommend naming it shell-date or git-date (e.g. shell-2017-03-20), depending on what lesson you're teaching.
Enable github pages on the master branch in the repository settings.
Add the ssh key you generated to your github account (use the contents of ~/.ssh/github.key.pub
).
Clone your repository to your local system (where you'll be teaching from).
$ cd ~
$ git clone [email protected]:your_github_username/your_repo_name.git
Start transcribing your terminal:
$ bash ~/your_repo_name/start_transcript.sh
Your prompt will be set to "$ " in the current terminal (Linux, Mac) or in a new terminal (git bash, Cygwin) and all commands you enter and their output will be recorded. A new terminal window will open and start the auto_push.sh
script to push the transcripts to github. The transcripts will be accessible at https://your_github_username.github.io/your_repo_name.
To leave your prompt unchanged, run bash ~/your_repo_name/start_transcript.sh --keep-prompt
Some files will be created:
commands.txt
-- command history with no outputfull_terminal.script
-- full output from thescript
command (commands and output) including ANSI escape sequences (created on Linux and Mac)full_terminal.d
-- directory with sequentially numbered files of the log output frommintty.exe
(created on Windows with git bash or Cygwin, equivalent to the output fromscript
)full_terminal.pipe
-- named pipe where the script command can immediately flush output (created on Mac; the included version ofscript
doesn't have the option to do this directly to a regular file)full_terminal.html
-- output fromscript
ormintty.exe
converted to html The providedindex.html
uses jquery to includefull_terminal.html
andcommands.txt
.
You'll want to do these steps when you're finished teaching:
- End the script recording in your teaching terminal (hit Ctrl-D or type "exit").
- Kill the
auto_push.sh
script (hit Ctrl-C in the terminal window). - Delete the ssh key from your github profile. (This is very important if you're teaching from a shared instructor station or any system that other people control or access since the key will allow pushes to your github account. You can skip this if you're using your own laptop.)
- Delete the github ssh key from
~/.ssh
and undo changes to~/.ssh/config
.