Command Line

Last updated on 2026-10-07 | Edit this page

Overview

Questions

  • How can I make my results easier to reproduce?

Objectives

  • Introduce Zipf’s Law project.
  • Introduce git tags and branches
  • Illustrate pain and fragility of building with editor and sequences of command line commands.

Let’s imagine that you are writing code for a research project to test Zipf’s Law.

Callout

Zipf’s Law

The most frequently-occurring word occurs approximately twice as often as the second most frequent word. This is [Zipf’s Law][zipfs-law].

We have setup a git repository with a sequence of branches to step through the tutorial today. You should start by cloning the repository

BASH 

$ git clone repository work_dir

OUTPUT 

Cloning into 'work_dir'...
done.

Change to the new directory, checkout the branch 06-documentation, and list the branches

BASH 

$ cd work_dir
$ git checkout 06-documentation
$ git branch -a

OUTPUT 

* 06-documentation
  remotes/origin/01-command-line
  remotes/origin/02-first-makefile
  remotes/origin/03-no-hands
  remotes/origin/04-testing
  remotes/origin/05-standards
  remotes/origin/06-documentation
  remotes/origin/HEAD -> origin/06-documentation
  remotes/origin/main

Today, we will start with the branch 01-command-line and step through the numbered branches arriving at the branch 06-documentation which uses all of the tool we will introduce.

First let’s peek at the final results

BASH 

$ make

View the result with (depending on your OS)

BASH 

$ evince build/report.pdf

BASH 

$ make docs

View the result with (depending on your OS)

BASH 

$ firefox build/docs/html/index.html

Let’s take a couple of minutes to skim the document.

Now clean up and start with the 01-command-line branch

BASH 

$ make clean
$ git switch -c my-01-branch remotes/origin/01-command-line
$ ls

The output of the last command should be

OUTPUT 

README  abyss.txt  analyze.py  isles.txt  local.bib  report.tex

Now build the document pdf by following the instructions in the README file:

First run the analysis script and display the first ten lines of the results in abyss.dat

BASH 

$ python analyze.py abyss.txt abyss.dat abyss.pdf
$ python analyze.py isles.txt isles.dat isles.pdf
$ head -10 abyss.dat

Then use an editor to copy results from the screen into report.tex

BASH 

$ emacs report.tex

Now run latexmk to build the pdf

BASH 

$ latexmk -pdf report.tex

If you are not sure you did it right, you can start over by running:

BASH 

$ rm *.dat *.pdf *.aux *.bbl *.blg *.fdb_latexmk *.fls

or if you have clobbered some source files:

$ rm * ; git checkout .
Key Points
  • We hope to improve on executing commands from a README