From 7fce0198fb88290026107647a13f22bf539216df Mon Sep 17 00:00:00 2001
From: Richard Darst <rkd@zgib.net>
Date: Tue, 12 Sep 2023 23:07:58 +0300
Subject: [PATCH] Change `<var>` to `VAR` throughout

- As discussed in chat (but not yet agreed)
- Ran the command `sed -i -E 's/<([0-9a-zA-Z_-]+)>/\U\1/g'
  content/*.md` but also checked each with "meld" and removed cases
  that shouldn't be changed (like git command outputs)
  - If git command hints use `<var>` maybe that's a reason to not
    change?
- Also changed some cases which weren't in angle brackets yet.
- Time taken: about 5 minutes.
- Review
  - There's a real chocie here: is this a good idea or not?  I'm not
    sure, I've done this to see how hard it would be, not because it
    should be done.
  - Advantages: perhaps more clear what should be replaced and that
    `<>` are not part of the syntax?  Upper case easier to scan and
    see?
  - Disadvanages: unclear what is a replacement and what is not?  (I
    didn't see any places that wolud be the case.)  Different than
    what others use?
  - The biggest disadvantage is that `HEAD` is actually a literal that
    is used in git... which *is* ambiguous.
---
 content/archaeology.md | 18 +++++++++---------
 content/basics.md      | 14 +++++++-------
 content/branches.md    | 16 ++++++++--------
 content/interrupted.md |  4 ++--
 content/recovering.md  | 16 ++++++++--------
 content/reference.md   | 22 +++++++++++-----------
 content/remotes.md     | 12 ++++++------
 7 files changed, 51 insertions(+), 51 deletions(-)

diff --git a/content/archaeology.md b/content/archaeology.md
index f085d310..c816cf29 100644
--- a/content/archaeology.md
+++ b/content/archaeology.md
@@ -55,7 +55,7 @@ With `git grep` you can find all lines in a repository which contain some string
 This is useful to find out where in the code some variable is used or some error message printed:
 
 ```console
-$ git grep sometext
+$ git grep TEXT
 $ git grep "some text with spaces"
 ```
 
@@ -78,7 +78,7 @@ We have seen this one before already. Using `git show` we can inspect an individ
 we know its hash:
 
 ```console
-$ git show somehash
+$ git show HASH
 ```
 
 For instance:
@@ -95,7 +95,7 @@ last. It also prints the precise hash of the last change which modified each lin
 for reproducibility.
 
 ```console
-$ git annotate somefile
+$ git annotate FILE
 ```
 
 Example:
@@ -122,7 +122,7 @@ We can create branches pointing to a commit in the past.
 This is the recommended mechanism to inspect old code:
 
 ```console
-$ git switch --create branchname somehash
+$ git switch --create BRANCHNAME HASH
 ```
 
 Example (lines starting with "#" are only comments):
@@ -144,7 +144,7 @@ $ git branch -d older-code
 On newer Git versions this is the preferred command:
 
 ```console
-$ git switch --create branchname somehash
+$ git switch --create BRANCHNAME HASH
 ```
 
 (exercise-history)=
@@ -249,7 +249,7 @@ We will probably arrive at a solution which is similar to `git bisect`:
   ```
 - Then bisect/iterate your way until you find the commit that broke it.
 - If you want to go back to start, type `git bisect reset`.
-- This can even be automatized with `git bisect run <script>`.
+- This can even be automatized with `git bisect run SCRIPT`.
   For this you write a script that returns zero/non-zero (success/failure).
 
 (exercise-bisect)=
@@ -308,17 +308,17 @@ We will probably arrive at a solution which is similar to `git bisect`:
 
   How to navigate to the parent of a commit with hash `somehash`:
   ```console
-  $ git switch --create branchname somehash~1
+  $ git switch --create BRANCHNAME SOMEHASH~1
   ```
 
   Instead of a tilde you can also use this:
   ```console
-  $ git switch --create branchname somehash^
+  $ git switch --create BRANCHNAME SOMEHASH^
   ```
 ````
 
 ```{keypoints}
 - git log/grep/annotate/show/bisect is a powerful combination when doing archaeology in a project.
-- `git switch --create <name> <hash>` is the recommended mechanism to inspect old code.
+- `git switch --create NAME HASH` is the recommended mechanism to inspect old code.
 - On newer Git you can use the more intuitive `git switch --create branchname somehash`.
 ```
diff --git a/content/basics.md b/content/basics.md
index 1ab64e68..f61c9f21 100644
--- a/content/basics.md
+++ b/content/basics.md
@@ -31,10 +31,10 @@
 - Example (we don't need to type yet):
 
   ```console
-  $ git add somefile.txt
+  $ git add FILE.txt
   $ git commit
 
-  $ git add file.txt anotherfile.txt
+  $ git add FILE.txt ANOTHERFILE.txt
   $ git commit
   ```
 
@@ -314,8 +314,8 @@ Date:   Wed Feb 9 10:11:30 2022 +0100
 ## Optional exercises: comparing, renaming, and removing
 
 ```{exercise} (optional) Basic-2: Comparing and showing commits
-1. Inspect differences between commit hashes with `git diff <hash1> <hash2>`.
-2. Have a look at specific commits with `git show <hash>`.
+1. Inspect differences between commit hashes with `git diff HASH1 HASH2`.
+2. Have a look at specific commits with `git show HASH`.
 ```
 
 ````{exercise} (optional) Basic-3: Visual diff tools
@@ -323,12 +323,12 @@ Date:   Wed Feb 9 10:11:30 2022 +0100
 
   On Windows or Linux:
   ```console
-  $ git difftool --tool=meld <hash>
+  $ git difftool --tool=meld HASH
   ```
 
   On macOS:
   ```console
-  $ git difftool --tool=opendiff <hash>
+  $ git difftool --tool=opendiff HASH
   ```
 
   ```{figure} img/meld.png
@@ -478,7 +478,7 @@ But it is also possible to work from within a Git graphical user interface (GUI)
 Now we know how to save snapshots:
 
 ```console
-$ git add <file(s)>
+$ git add FILE(S)
 $ git commit
 ```
 
diff --git a/content/branches.md b/content/branches.md
index e93fa398..542a21d5 100644
--- a/content/branches.md
+++ b/content/branches.md
@@ -549,24 +549,24 @@ Let us pause for a moment and recapitulate what we have just learned:
 
 ```console
 $ git branch               # see where we are
-$ git branch <name>        # create branch <name>
-$ git switch <name>        # switch to branch <name>
-$ git merge <name>         # merge branch <name> (to current branch)
-$ git branch -d <name>     # delete branch <name>
-$ git branch -D <name>     # delete unmerged branch
+$ git branch NAME          # create branch NAME
+$ git switch NAME          # switch to branch NAME
+$ git merge NAME           # merge branch NAME (to current branch)
+$ git branch -d NAME       # delete branch NAME
+$ git branch -D NAME       # delete unmerged branch
 ```
 
 Since the following command combo is so frequent:
 
 ```console
-$ git branch <name>        # create branch <name>
-$ git switch <name>        # switch to branch <name>
+$ git branch NAME          # create branch NAME
+$ git switch NAME          # switch to branch NAME
 ```
 
 There is a shortcut for it:
 
 ```console
-$ git switch --create <name>  # create branch <name> and switch to it
+$ git switch --create NAME  # create branch NAME and switch to it
 ```
 
 ### Typical workflows
diff --git a/content/interrupted.md b/content/interrupted.md
index 1772c5b8..7e0a58c4 100644
--- a/content/interrupted.md
+++ b/content/interrupted.md
@@ -65,7 +65,7 @@ things.
    stashed?
 
 ```{solution}
-5: Yes you can. With `git stash pop <index>` you can decie which stash
+5: Yes you can. With `git stash pop INDEX` you can decie which stash
 index to pop.
 
 6: In this case Git will ask us to resolve the conflict the same way
@@ -86,7 +86,7 @@ You basically know how to do this:
 
 ```console
 $ git switch --create temporary  # create a branch and switch to it
-$ git add <paths>                # stage changes
+$ git add PATHS                  # stage changes
 $ git commit                     # commit them
 $ git switch main                # back to main, continue your work there ...
 $ git switch temporary           # continue where you left off
diff --git a/content/recovering.md b/content/recovering.md
index 335a97b4..9c7f1b1a 100644
--- a/content/recovering.md
+++ b/content/recovering.md
@@ -51,7 +51,7 @@ You can always do that with:
 
 Or, you can undo things selectively:
 
-- `git restore -p` (decide which portions of changes to undo) or `git restore <path>` (decide which path/file)
+- `git restore -p` (decide which portions of changes to undo) or `git restore PATH` (decide which path/file)
 
 If you have staged changes, you have at least two options to undo the staging:
 - `git restore --staged .` followed by `git status` and `git restore .`
@@ -145,7 +145,7 @@ This means that we avoid this command on commits that we have shared with others
 You can **reset branch history** to move your branch back to some
 point in the past.
 
-* `git reset --hard <hash>` will force a branch label to any other point.  All
+* `git reset --hard HASH` will force a branch label to any other point.  All
   other changes are lost (but it is possible to recover if you force reset by mistake).
 * Be careful if you do this - it can mess stuff up.  Use `git graph` a
   lot before and after.
@@ -160,8 +160,8 @@ point in the past.
   all of that and get our repositories to a similar state.
 
   - First, we will look at our history (`git log`/`git graph`) and
-    find the last commit `<hash>` before our tests.
-  - Then, we will `git reset --hard <hash>` to that.
+    find the last commit `HASH` before our tests.
+  - Then, we will `git reset --hard HASH` to that.
   - Then, `git graph` again to see what happened.
 
   ```console
@@ -198,16 +198,16 @@ wrong branch.
 **Solution 1 using git cherry-pick**:
 1. Make sure that the correct branch exists and if not, create it. Make sure to
    create it from the commit hash where you wish you had created it from: `git
-   branch <branchname> <hash>`
+   branch BRANCHNAME HASH`
 2. Switch to the correct branch.
-3. `git cherry-pick <hash>` can be used to take a specific commit to the
+3. `git cherry-pick HASH` can be used to take a specific commit to the
    current branch. Cherry-pick all commits that should have gone to the correct
    branch, **from oldest to most recent**.
 4. Rewind the branch that accidentally got wrong commits with `git reset --hard` (see also above).
 
 **Solution 2 using git reset --hard** (makes sense if the correct branch should
 contain all commits of the accidentally modified branch):
-1. Create the correct branch, pointing at the latest commit: `git branch <branchname>`.
+1. Create the correct branch, pointing at the latest commit: `git branch BRANCHNAME`.
 2. Check with `git log` or `git graph` that both branches point to the same, latest, commit.
 3. Rewind the branch that accidentally got wrong commits with `git reset --hard` (see also above).
 
@@ -219,7 +219,7 @@ the other branch. But sometimes we run this command on the wrong branch.
 
 1. Check with `git log` the commit hash that you would like to rewind the
    wrongly modified branch to.
-2. Rewind the branch that accidentally got wrong commits with `git reset --hard <hash>` (see also above).
+2. Rewind the branch that accidentally got wrong commits with `git reset --hard HASH` (see also above).
 
 
 ## Recovering from conflict after git pull
diff --git a/content/reference.md b/content/reference.md
index f2d4821f..ef164af1 100644
--- a/content/reference.md
+++ b/content/reference.md
@@ -42,23 +42,23 @@ See our status:
   with `git config --global alias.graph "log --all --graph --decorate --oneline"`
 * `git diff`: show difference between working directory and last commit
 * `git diff --staged`: show difference between staging area and last commit
-* `git show <commit>`: inspect individual commits
+* `git show COMMIT`: inspect individual commits
 
 General work:
 
-* `git add`:
+* `git add FILE`:
   - Add a new file
   - Add a file to staging
 * `git commit`: record a version, add it to current branch
 * `git commit --amend`: amend our last commit
 * `git branch`: show which branch we're on
-* `git branch <name>`: create a new branch called "name"
-* `git restore <file>`: restore last committed/staged version of &lt;file&gt;, losing unstaged changes
-* `git switch --create <branch-name>`: create a new branch and switch to it
-* `git revert abc123`: create a new commit which reverts commit abc123
-* `git reset --soft abc123`: remove all commits after abc123, but keep their modifications as staged changes
-* `git reset --hard abc123`: remove all commits after abc123, permanently throwing away their changes
-* `git merge <branch-name>`: merge branch &lt;branch-name&gt; into current branch
-* `git grep`: search for patterns in tracked files
-* `git annotate`: find out when a specific line got introduced and by whom
+* `git branch NAME`: create a new branch called "name"
+* `git restore FILE`: restore last committed/staged version of FILE, losing unstaged changes
+* `git switch --create BRANCH-NAME`: create a new branch and switch to it
+* `git revert HASH`: create a new commit which reverts commit HASH
+* `git reset --soft HASH`: remove all commits after HASH, but keep their modifications as staged changes
+* `git reset --hard HASH`: remove all commits after HASH, permanently throwing away their changes
+* `git merge BRANCH-NAME`: merge branch BRANCH-NAME into current branch
+* `git grep PATTERN`: search for patterns in tracked files
+* `git annotate FILE`: find out when a specific line got introduced and by whom
 * `git bisect`: find a commit which broke some functionality
diff --git a/content/remotes.md b/content/remotes.md
index ab13e137..b4bcdd80 100644
--- a/content/remotes.md
+++ b/content/remotes.md
@@ -147,10 +147,10 @@ We now want to try the second option that GitHub suggests:
 1. Now go to your guacamole repository on your computer.
 2. Check that you are in the right place with `git status`.
 3. Copy paste the three lines to the terminal and execute those, in my case (**you
-  need to replace the "user" part and possibly also the repository name**):
+  need to replace the "USER" part and possibly also the repository name**):
 
   ```console
-  $ git remote add origin git@github.com:user/recipe.git
+  $ git remote add origin git@github.com:USER/recipe.git
   $ git branch -M main
   $ git push -u origin main
   ```
@@ -167,7 +167,7 @@ Enumerating objects: 3, done.
 Counting objects: 100% (3/3), done.
 Writing objects: 100% (3/3), 221 bytes | 221.00 KiB/s, done.
 Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
-To github.com:user/recipe.git
+To github.com:USER/recipe.git
  * [new branch]      main -> main
 Branch 'main' set up to track remote branch 'main' from 'origin'.
 ```
@@ -177,7 +177,7 @@ Branch 'main' set up to track remote branch 'main' from 'origin'.
 ```{exercise} Push-1: Push your guacamole recipe to GitHub
 - Go to your recipe directory on your computer.
 - Check that you are in the right place with `git status`.
-- Define the remote with `git remote add origin git@github.com:user/recipe.git`.
+- Define the remote with `git remote add origin git@github.com:USER/recipe.git`.
 - Rename the current branch to "main", if needed: `git branch -M main`.
 - Push the local branch "main" to the remote: `git push -u origin main`.
 ```
@@ -199,14 +199,14 @@ At this point only a brief demo - if you copy the SSH or HTTPS address, you can
 (again adapt the "namespace/repository.git" part):
 
 ```console
-$ git clone git@github.com:user/recipe.git
+$ git clone git@github.com:USER/recipe.git
 ```
 
 This creates a directory called "recipe" unless it already exists. You can also specify the target directory
 on your computer:
 
 ```console
-$ git clone git@github.com:user/recipe.git myrecipe
+$ git clone git@github.com:USER/recipe.git myrecipe
 ```
 
 What just happened? **Think of cloning as downloading the `.git` part to your