6. Terminal

6.1. Course Workflow

Make sure you check out this flowchart that explains class workflow to make sure you’re following along correctly

---

6.2. What’s happening on this terminal?

Someone asked “How do we make sure a pr’s name is good enough for us to get credit on the badge?

Answere: Well, you can use the same tool that I use for grading courseutils

Let’s try it together

$ cspt checktitle "pracitce  2-11"

Usage: cspt [OPTIONS] COMMAND [ARGS]...
Try 'cspt --help' for help.

Error: No such command 'checktitle'.

Hmmm… What went wrong?

Looks like I have the command checktitle wrong.

Of course I’m not going to memorize it if I don’t need to. I’m a software engineer, I use different tools on the terminal daily. I memorize most of them because of practice. What’s important is not to memorize commands but to know where to find them and how to learn about them.

---

Well, how do we do that?

$ cspt --help

Usage: cspt [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  badge           log an additional badge that is not in the pr list
  badgecounts     check if early bonus is met from output of `gh pr list...
  combinecounts   combine two yaml files by adding all keys and summing...
  createtoyfiles  from a yaml source file create a set of toy files with...
  earlybonus      check if early bonus is met from output of `gh pr list...
  eventbonus      award a bonus,
  exportac        export ac files for site from lesson
  exporthandout   export prismia version of the content
  exportprismia   export prismia version of the content
  getassignment   get the assignment text formatted
  getbadgedate    cli for calculate badge date
  glossify        overwrite a file with all glossary terms using the term...
  grade           calculate a grade from yaml that had keys of...
  issuestat
  issuestatus     generate script to appy course issue statuse updates
  kwlcsv          generate the activity file csv file for the site...
  logquestion     award a bonus,
  mkchecklist     transform input file to a gh markdown checklist, if the...
  parsedate       process select non dates
  prfixlist       check json output for titles that will not be counted...
  processexport   transform output from mac terminal export to myst...
  progressreport  list PR titles from json or - to use std in that have...
  titlecheck      check a single title

This line Usage: cspt [OPTIONS] COMMAND [ARGS]... is what I like to call a signiture line.

It tell us what the shape of a command in cspt would look like.

If we dissect the line:

• cspt: The name of the program/tool

• [OPTIONS]: Mostly optional option/flag that you want your command to include

Understanding this piece comes with practice.

This of a command like commit. We’ve used git commit as is before, and the command executed, but we still needed to include a commit message and that’s why “git” forced us into vim to type a commit message. So, the option -m was partially optional, but when we use it, we simply add the message right after in double-quotes in the same command and that saves us the trouble.

We’ve also used the option -a with git commit last class. And we that we simply asked git to allow us to skip doing git add . and for it to do it for us. Or when we created a new local branch with the checkout command we used the option -b to ask git to create a new branch and then checkout/switch to it.

• COMMAND: There a list of commands that this tool will execute for you. Pick one

• [ARGS]: If the command requires an argument (mostly a type of input) pass it/add it here

$ cspt titlecheck "pracitce  2-11"

Usage: cspt titlecheck [OPTIONS]
Try 'cspt titlecheck --help' for help.

Error: Got unexpected extra argument (pracitce  2-11)

Ok, my command is still missing something, or has something extra (it says extra agrs, but is that really the problem?)

$ cspt titlecheck --help

Usage: cspt titlecheck [OPTIONS]

  check a single title

Options:
  -t, --pr-title TEXT  title to check as string
  -g, --ghpr FILENAME  pass title as file, or gh pr view output through pipe
  --help               Show this message and exit.

Looks like we’re missing an option. Aha, not so optional this time…

Notice in this help message we see -t, --pr-title TEXT title to check as string If we dissect this line:

• -t & --pr-title: are representations of the same option. The developer of this tool (Dr. Sarah Brown) has given the user two ways of using this option, a short way -t and a long way --pr-title

• Text: This is the argument we’re passing this command. In this case this is a string with the pull request title

• title to check as string: Description

Question: Will there always be a short and a long way to set a flag (option)? Answer: Not necessarily, this is a convention that a lot of developers abide by. Similar to when you write a variable name in your programming language of choice: In python programmers use snake_case In C & C++ programmers mostly use camelCase And these are not rules that if you don’t abide by your program will crash. These are naming conventions that are just known and used by most programmers.

$ cspt titlecheck -t "pracitce  2-11"

missing a badge type keyword.

Getting closer. I misspelled Practice.

$ cspt titlecheck -t "practice  2-11"

missing or poorly formatted date

$ cspt titlecheck -t "practice  2-11-2025"

good

$ cspt titlecheck -t "practice  2025-2-11"

good

$ cspt titlecheck -t "practice  2/11/2025"

good

We can use the --help/-h option with more tools

$ gh -h

Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  auth:        Authenticate gh and git with GitHub
  browse:      Open the repository in the browser
  codespace:   Connect to and manage codespaces
  gist:        Manage gists
  issue:       Manage issues
  org:         Manage organizations
  pr:          Manage pull requests
  project:     Work with GitHub Projects.
  release:     Manage releases
  repo:        Manage repositories

GITHUB ACTIONS COMMANDS
  cache:       Manage Github Actions caches
  run:         View details about workflow runs
  workflow:    View details about GitHub Actions workflows

EXTENSION COMMANDS
  classroom:   Extension classroom

ALIAS COMMANDS
  co:          Alias for "pr checkout"

ADDITIONAL COMMANDS
  alias:       Create command shortcuts
  api:         Make an authenticated GitHub API request
  completion:  Generate shell completion scripts
  config:      Manage configuration for gh
  extension:   Manage gh extensions
  gpg-key:     Manage GPG keys
  label:       Manage labels
  ruleset:     View info about repo rulesets
  search:      Search for repositories, issues, and pull requests
  secret:      Manage GitHub secrets
  ssh-key:     Manage SSH keys
  status:      Print information about relevant issues, pull requests, and notifications across repositories
  variable:    Manage GitHub Actions variables

HELP TOPICS
  actions:     Learn about working with GitHub Actions
  environment: Environment variables that can be used with gh
  exit-codes:  Exit codes used by gh
  formatting:  Formatting options for JSON data exported from gh
  mintty:      Information about using gh with MinTTY
  reference:   A comprehensive reference of all gh commands

FLAGS
  --help      Show help for command
  --version   Show gh version

EXAMPLES
  $ gh issue create
  $ gh repo clone cli/cli
  $ gh pr checkout 321

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

---

Terminal is an interface for a shell

---

A shell is the outermost layer of an operating system, It is the way for users to communicate or interact with the operating system and make commands

---

It is very powerful

---

The terminal has programs installed on it such as nano, cat, git and more… And it has commands that it recognizes echo, cd, pwd, etc…

$ echo hello

hello

$ 5+2

bash: 5+2: command not found

Again, I don’t have the syntax here memorized, but I can get there I’m sure…

$ 5+2

bash: 5+2: command not found

$ $(5+2)

bash: 5+2: command not found

$ $((5+2))

bash: 7: command not found

Aha!! Notice: this time we got the syntax for mathematical operation correct in bash. Because this time bash this time evaluated the result and then told us this is not a command

Let’s try this one last time

$ echo $((5+2))

7

With this command, we asked bash to echo(print out) the evaluated value of 5+2

$((5+2)) here was an argument.

---

cat -h

cat: unknown option -- h
Try 'cat --help' for more information.

Hmmm, cat doesn’t have the -h option. What if…

cat --help

---

Usage: cat [OPTION]... [FILE]...
Concatenate FILE(s) to standard output.

With no FILE, or when FILE is -, read standard input.

  -A, --show-all           equivalent to -vET
  -b, --number-nonblank    number nonempty output lines, overrides -n
  -e                       equivalent to -vE
  -E, --show-ends          display $ at end of each line
  -n, --number             number all output lines
  -s, --squeeze-blank      suppress repeated empty output lines
  -t                       equivalent to -vT
  -T, --show-tabs          display TAB characters as ^I
  -u                       (ignored)
  -v, --show-nonprinting   use ^ and M- notation, except for LFD and TAB
      --help     display this help and exit
      --version  output version information and exit

Examples:
  cat f - g  Output f's contents, then standard input, then g's contents.
  cat        Copy standard input to standard output.

GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
Report any translation bugs to <https://translationproject.org/team/>
Full documentation <https://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'

AH!! cat didn’t have the short option for the option --help

---

Someone asked “How can a terminal command gh repo view --web open a browser tab?

gh (program/tool) repo (command) view (subcommand) --web/ -w (options/flags)

6.3. Prepare for next class

No prepare work for next class

6.4. Badges

Review

1. [ ] Look over the class notes and answer the following in a file called cat.md

What happens if we typed the command

cat

exactly as is. Feel free to test it on your terminal.

Tell me what the --help message told you regarding the command being run like so. And give me a brief explaination in your own words of what that means.

Practice

1. [ ] Look over the class notes and answer the following in a file called cat.md

What happens if we typed the command

cat

exactly as is. Feel free to test it on your terminal.

Tell me what the --help message told you regarding the command being run like so. And give me a brief explaination in your own words of what that means.

1. [ ] Use the option -h/--help with one command that we’ve with so far. Read the explaination thoroughly and write a short report in a file named command-help.md that explains your findings.

# Command
<!-- Command name -->

## Command use

## Command example dissected

## Reflection

<!-- Was there anything about the use of this command that you didn't know before doing this activity and thought was cool? -->

<!-- Did you find hardship reading the documentation for the command? -->

<!-- Did you do this for more than one command? Type the other commands you've used the `-h` option with and anything cool that you found -->