markdown source builds

Auto-generated via `{sandpaper}` Source : 5305aa7 Branch : main Author : Dimitrios Theodorakis <[email protected]> Time : 2024-12-19 16:59:07 +0000 Message : MetOffice#99 Re-work the structure of the config lesson and add recommendations in the discussion page
astroDimitrios · Dec 19, 2024 · 0e2e36e · 0e2e36e
1 parent 365f610
commit 0e2e36e
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 20 deletions.
diff --git a/02-setup.md b/02-setup.md
@@ -25,8 +25,14 @@ of configurations we will set as we get started with Git:
 - what our preferred text editor is,
 - and that we want to use these settings globally (i.e. for every project).
 
+## Command Line Git Setup
+
 On a command line, Git commands are written as `git verb options`,
-where `verb` is what we actually want to do and `options` is additional optional information which may be needed for the `verb`. To set up a new computer:
+where `verb` is what we actually want to do and `options` is additional optional information which may be needed for the `verb`.
+
+### Authorship
+
+To set up a new computer:
 
 ```bash
 $ git config --global user.name "Joanne Simpson"
@@ -52,9 +58,7 @@ If you elect to use a private email address with GitHub, then use GitHub's no-re
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
-:::::::::::::::::::::::::::::::::::::::::  callout
-
-## Line Endings
+### Line Endings
 
 As with other keys, when you press <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd> on your keyboard,
 your computer encodes this input as a character.
@@ -69,19 +73,23 @@ You can change the way Git recognizes and encodes line endings
 using the `core.autocrlf` command to `git config`.
 The following settings are recommended:
 
-On macOS and Linux:
+::: group-tab
+
+### Linux & MacOS
 
 ```bash
 $ git config --global core.autocrlf input
 ```
 
-And on Windows:
+### Windows
 
 ```bash
 $ git config --global core.autocrlf true
 ```
 
-::::::::::::::::::::::::::::::::::::::::::::::::::
+:::
+
+### Text Editor
 
 To set your preferred text editor, 
 find the correct configuration command from this table:
@@ -117,6 +125,8 @@ If you want to save your changes and quit, press <kbd>Esc</kbd> then type `:wq`
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+### Default Branch Name
+
 Git (2.28+) allows configuration of the name of the branch created when you
 initialize any new repository. We want to set this to `main` so
 it matches the cloud service we will eventually use.
@@ -127,10 +137,9 @@ $ git config --global init.defaultBranch main
 
 :::::::::::::::::::::::::::::::::::::::::  callout
 
-## Default Git branch naming
+## History of `main`
 
-Source file changes are associated with a "branch."
-For new learners in this lesson, it's enough to know that branches exist, and this lesson uses one branch.  
+Source file changes are associated with a "branch".
 By default, Git will create a branch called `master`
 when you create a new repository with `git init` (as explained in the next Episode). This term evokes
 the racist practice of human slavery and the
@@ -151,22 +160,27 @@ configuration, the `init.defaultBranch` value defaults to `master`.
 The five commands we just ran above only need to be run once: the flag `--global` tells Git
 to use the settings for every project, in your user account, on this computer.
 
+## Text Editor Git Setup
+
 Let's review those settings and test our `core.editor` right away:
 
 ```bash
 $ git config --global --edit
 ```
 
-Let's close the file without making any additional changes.  Remember, since typos in the config file will cause
-issues, it's safer to view the configuration with:
+Let's close the file without making any additional changes.
+Since typos in the config file will cause issues,
+it's safer to view the configuration with:
 
 ```bash
 $ git config --list
 ```
 
-And if necessary, change your configuration using the
-same commands to choose another editor or update your email address.
-This can be done as many times as you want.
+And alter the configuration via the command line.
+You can re-run the commands above as many times as you want
+to change your configuration.
+The [discussion](../learners/discuss.md#more-advanced-git-configuration)
+page has details on more recommended settings.
 
 :::::::::::::::::::::::::::::::::::::::::  callout
 
@@ -194,7 +208,7 @@ $ git config --global --unset https.proxy
 
 ## Git Help and Manual
 
-Always remember that if you forget the subcommands or options of a `git` command, you can access the
+If you forget the subcommands or options of a `git` command, you can access the
 relevant list of options typing `git <command> -h` or access the corresponding Git manual by typing
 `git <command> --help`, e.g.:
 
@@ -221,5 +235,3 @@ $ git help
 - Use `git config` with the `--global` option to configure a user name, email address, editor, and other preferences once per machine.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-
diff --git a/discuss.md b/discuss.md
@@ -42,6 +42,42 @@ The available options are described in the manual:
 $ git config --help
 ```
 
+### Recommended Settings
+
+We recommend setting the following:
+
+```gitconfig
+[merge]
+    ff = false
+    conflictStyle = diff3
+[mergetool]
+    keepBackup = false
+[fetch]
+    prune = true
+[pull]
+    ff = only
+```
+
+| Setting              | Value | Justification                                              |
+|----------------------|-------|------------------------------------------------------------|
+| merge.ff             | false | Make `git merge` always a "true merge"                     |
+| merge.conflictStyle  | diff3 | Add common ancestor to conflict markers                    |
+| mergetool.keepBackup | false | Tidy `*.orig` files when `mergetool` finishes              |
+| fetch.prune          | true  | Automatically delete references to deleted remote branches |
+| pull.ff              | only  | Make `git pull` only fast-forward                          |
+
+These settings will be explained in later episodes
+and in the follow on Git & GitHub Working Practices training.
+
+Set them using:
+
+```bash
+$ git config --global setting value
+$ git config --global merge.ff false
+```
+
+#### Aliases
+
 In particular, you might find it useful to add aliases.
 These are like shortcuts for longer Git commands.
 For example, if you get sick of typing `git checkout` all the time,
@@ -63,6 +99,66 @@ we could now instead type:
 $ git co f22b25e forecast.md
 ```
 
+The following are some aliases others have found useful.
+We recommend returning to these once you have learnt more
+Git commands and become more comfortable with Git in general.
+
+```gitconfig
+[alias]
+    st = status
+    ci = commit
+    ca = commit -a
+    br = branch
+    co = checkout
+    cb = checkout -b
+    lg = log --oneline
+    graph = log --oneline --graph
+    dog = log --decorate --oneline --graph
+    sdiff = diff --staged
+    unstage = restore --staged
+    amend = commit --amend --no-edit
+    reword = commit --amend --only --
+    ff = merge --ff-only
+    update = "! git pull --ff-only && git push"
+```
+
+Set them using:
+
+```bash
+$ git config --global alias.<short> "<command>"
+$ git config --global alias.st "status"
+```
+
+### Viewing Settings
+
+```bash
+git config --list --show-origin  # Shows all configurations with their origins
+git config --global --list       # Shows global configurations
+git config --local --list        # Shows configurations for the current repository
+```
+
+### Removing Settings
+
+The following actions can **NOT** be undone.
+Be certain you wish to delete any settings.
+Simply add `--unset` before the key:
+
+```bash
+$ git config --global --unset alias.st
+```
+
+You may wish to completely clear your global settings:
+
+```bash
+$ rm ~/.gitconfig
+```
+
+Or your local settings:
+
+```bash
+$ rm .git/config
+```
+
 ## Styling Git's Log
 
 A good target for customization is output from the log.

diff --git a/md5sum.txt b/md5sum.txt
@@ -4,7 +4,7 @@
 "config.yaml" "63bad31d602badcc1d33437fc70cb758" "site/built/config.yaml" "2024-12-19"
 "index.md" "5805bcbdc567c8268e51d1c24d354dbe" "site/built/index.md" "2024-12-18"
 "episodes/01-basics.md" "36fa3fb584418a201fd43e7f1f84f920" "site/built/01-basics.md" "2024-12-19"
-"episodes/02-setup.md" "6d98278b0632471e50348256503c7c69" "site/built/02-setup.md" "2024-12-03"
+"episodes/02-setup.md" "bef872b386e3793f930d052caa2c2dd8" "site/built/02-setup.md" "2024-12-19"
 "episodes/03-create.md" "80501395036c8964535186d8fc5750a7" "site/built/03-create.md" "2024-12-19"
 "episodes/09-branches.md" "4fe0222ae69efeb99597da0228402159" "site/built/09-branches.md" "2024-12-19"
 "episodes/04-changes.md" "ccacb3193dbc9778103fd746a3a15881" "site/built/04-changes.md" "2024-12-19"
@@ -24,7 +24,7 @@
 "episodes/13-hosting.md" "c390f6e5ab0017576241ff881a26604c" "site/built/13-hosting.md" "2024-12-03"
 "episodes/14-supplemental-rstudio.md" "90970ec2287448cddbf421140d501834" "site/built/14-supplemental-rstudio.md" "2024-12-19"
 "instructors/instructor-notes.md" "f9d5f99b7121b74eb17e4eff63a319f4" "site/built/instructor-notes.md" "2024-12-19"
-"learners/discuss.md" "444aa49b1e84830f534916149bcf466d" "site/built/discuss.md" "2024-12-19"
+"learners/discuss.md" "998f06799541bd3b21247a709324a8ab" "site/built/discuss.md" "2024-12-19"
 "learners/fcm-git_cheat_sheet.md" "29ccb51a92f941d673f7a46d5c97b914" "site/built/fcm-git_cheat_sheet.md" "2024-12-12"
 "learners/reference.md" "4f100436a2f16b82e73515911e488a40" "site/built/reference.md" "2024-12-19"
 "learners/repo-quick-start.md" "84b7ee40a5b2bb149e97894869fda351" "site/built/repo-quick-start.md" "2024-12-12"