From 858da6b7186fee0dc868d13de383cbaba4930e5d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 20 Jan 2025 13:32:13 +0000 Subject: [PATCH] markdown source builds Auto-generated via `{sandpaper}` Source : 909f4e94a26b3962cefa663e087b2adc0e41f50c Branch : main Author : Dimitrios Theodorakis Time : 2025-01-20 13:30:27 +0000 Message : #106 Addresses review comments on Issue #105 Summary and Setup feedback * Addresses review comments on Issue 105 * Address review comments * Add version number disclaimer and note about nano and cat command usage --- index.md | 23 +++++-- md5sum.txt | 4 +- setup.md | 176 ++++++++++++++++++++++++++++++++++------------------- 3 files changed, 134 insertions(+), 69 deletions(-) diff --git a/index.md b/index.md index 09b620a2fd..32e67abd81 100644 --- a/index.md +++ b/index.md @@ -3,9 +3,13 @@ permalink: index.html site: sandpaper::sandpaper_site --- -[Version control](learners/reference.md#version-control) is fundamental to -good quality assurance of science and code. -Using a Version Control System is better than mailing files back and forth: +Welcome to the Introduction to Git and GitHub training! +This page contains learning outcomes +and setup that must be completed before working through the lesson. + +Version control is fundamental to good quality assurance of science and code. +Using a [Version Control System](learners/reference.md#version-control) +is better than mailing files back and forth: - Nothing that is committed to version control is ever lost, unless you work really, really hard at losing it. Since all old versions of @@ -40,10 +44,17 @@ to be shared can and should be stored in a version control system. ## Prerequisites -In this lesson we use Git from the Unix Shell. -Some previous experience with the shell is expected, +No knowledge of Git and GitHub is required. +In this lesson we use Git from the command line. +Some previous experience with the command line is expected, *but isn't mandatory*. +Access to the command line and +a browser connected to the Internet are required. :::::::::::::::::::::::::::::::::::::::::::::::::: - +This lesson is platform-independent and can be taken +on Linux, Windows, and MacOS. +This lesson has been fully tested on Linux. +If you encounter any problems using either Windows or MacOS +please [reach out for support](./learners/setup.md#how-to-get-help). diff --git a/md5sum.txt b/md5sum.txt index bf07dda670..40a664b931 100644 --- a/md5sum.txt +++ b/md5sum.txt @@ -2,7 +2,7 @@ "CODE_OF_CONDUCT.md" "c93c83c630db2fe2462240bf72552548" "site/built/CODE_OF_CONDUCT.md" "2024-12-03" "LICENSE.md" "b24ebbb41b14ca25cf6b8216dda83e5f" "site/built/LICENSE.md" "2024-12-03" "config.yaml" "190013a9a586c245b570a31a1a298275" "site/built/config.yaml" "2025-01-15" -"index.md" "5805bcbdc567c8268e51d1c24d354dbe" "site/built/index.md" "2024-12-18" +"index.md" "ca882861a56b733320045b01a6af1a0c" "site/built/index.md" "2025-01-20" "episodes/01-basics.md" "36fa3fb584418a201fd43e7f1f84f920" "site/built/01-basics.md" "2024-12-19" "episodes/02-setup.md" "3ba631342db50f2ce7a1090a908b1a75" "site/built/02-setup.md" "2024-12-19" "episodes/03-create.md" "80501395036c8964535186d8fc5750a7" "site/built/03-create.md" "2024-12-19" @@ -28,5 +28,5 @@ "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" -"learners/setup.md" "2f867eb017920df65cd3d2194c162f64" "site/built/setup.md" "2024-12-19" +"learners/setup.md" "45a74dc8e295fcbf531d174807da4b27" "site/built/setup.md" "2025-01-20" "profiles/learner-profiles.md" "b0aff1340a2ac3341ae4bdf26891da60" "site/built/learner-profiles.md" "2024-12-19" diff --git a/setup.md b/setup.md index a4c8dd6930..23626bca99 100644 --- a/setup.md +++ b/setup.md @@ -2,25 +2,79 @@ title: Setup --- -## Pre-workshop Survey +## How to get help -Please remember to fill out the pre-workshop survey prior -to the start of the workshop. +- Attend a Git and GitHub Surgery. +- Email the [support mailbox](mailto:ScienceGitMigrationProjectSupport@metoffice.gov.uk). + +Details of surgeries can be found on the +Science Git Migration Project Comms Site. + +## Lesson Outcomes + +This lesson is split into two parts. +Episodes in the first half before the break focus on Git. +Episodes in the second half after the break focus on GitHub. + +By the end of the Git section you will be able to: + +- describe the importance of Version Control. +- describe the similarities and differences between SVN and Git. +- configure Git. +- initialise new repositories using Git. +- develop changes on a branch. +- view differences between changes and explore your repositories history. + +By the end of the GitHub section you will be able to: + +- set up important GitHub settings and SSH access. +- describe the similarities and differences between Trac and GitHub. +- explain the differences between private, internal and public repositories. +- set up a repository, including how to protect the `main` branch and enable + wiki pages, discussions, and GitHub projects. +- view a repositories history and differences between changes. +- view Issues and Pull Requests. +- contribute changes to a repository using a Pull Request. + +And much more! + +## Pre-lesson Survey + +Please remember to fill out the +[pre-lesson survey](https://forms.office.com/e/XJPJUTn0mp) +prior to the start of the lesson. This information is vital for us to keep improving the lesson for other learners. ## Installing Git -Since several Carpentries lessons rely on Git, please see -[this section of the workshop template][workshop-setup] for -instructions on installing Git for various operating systems. +::: tab + +### Met Office Linux + +No setup is required, Git is installed for you. +Your version number may be different to the example below. + +```bash +$ git --version +git version 2.47.0 +``` + +### Met Office Windows + +Please ensure Git is installed via the Company Portal. +You should now have access to the **Git Bash** app. +Your version number may be different to the example below. + +```bash +$ git --version +git version 2.47.1.windows.1 +``` -- [Git installation on Windows][workshop-setup] -- [Git installation on MacOS][workshop-setup] -- [Git installation on Linux][workshop-setup] +### Non-Met Office Systems -Your institution may have already installed Git on your work computer. -Ask your instructor if this step is necessary or simply type: +The systems at your institution may already have Git installed. +You can check this by typing: ```bash $ git --version @@ -29,10 +83,16 @@ git version 2.47.0 If a version number is printed like the output above Git is installed and ready to use. +Otherwise please follow the instructions in the +[Git book](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +for your operating system. + +::: ## Creating a GitHub Account -You will need an account for [GitHub](https://github.com) to follow episodes 7 & 8 in this lesson. +You will need an account for [GitHub](https://github.com) to follow +the GitHub episodes of this lesson. 1. Go to and follow the "Sign up" link at the top-right of the window. 2. Follow the instructions to create an account. @@ -47,9 +107,9 @@ So if your name is `Eleanor Ormerod` your username would be: `mo-eormerod` In 2023, GitHub introduced a requirement for all accounts to have -[multi-factor authentication (2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) +[multi-factor authentication (MFA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) configured for extra security. -Several options exist for setting up 2FA, which are summarised here: +Several options exist for setting up MFA, which are summarised here: 1. If you already use an authenticator app, like [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en&co=GENIE.Platform%3DiOS&oco=0) @@ -58,19 +118,20 @@ Several options exist for setting up 2FA, which are summarised here: 2. If you have access to a smartphone but do not already use an authenticator app, install one and [add GitHub to the app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app). 3. If you do not have access to a smartphone or do not want to install an authenticator app, you have two options: - 1. [set up 2FA via text message](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages) + 1. [set up MFA via text message](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages) ([list of countries where authentication by SMS is supported](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported)), or 2. [use a hardware security key](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key) like [YubiKey](https://www.yubico.com/products/yubikey-5-overview/) or the [Google Titan key](https://store.google.com/us/product/titan_security_key?hl=en-US&pli=1). -The GitHub documentation provides [more details about configuring 2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). +The GitHub documentation provides [more details about configuring MFA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). ### Passkeys -To completely avoid having authentication for work purposes on a personal device you may choose to [set up a passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/managing-your-passkeys). Your instructor and organisation will be able to provide guidance on suitable passkey providers and password managers. - -[workshop-setup]: https://carpentries.github.io/workshop-template/install_instructions/#git +To completely avoid having authentication for work purposes on a personal device you may choose to [set up a passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/managing-your-passkeys). Your instructor or organisation will be able to provide guidance on suitable passkey providers and password managers. +At the Met Office the KeePass password manager is available. +Search, "Using KeePass for one-time passwords" on SharePoint for +setup instructions. ## Optional: Git Autocomplete @@ -79,15 +140,21 @@ terminal prompt. The following instructions have been tested on **Linux**. If you are using MacOS or Windows please consult the [Git autocomplete instructions](https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh) -at the top of the linked file. -Your instructor may point you to another online resource for your OS. -To enable this script add the following to a new `~/.bashrc.d/git.bash` +at the top of the linked file and +[reach out for support](./learners/setup.md#how-to-get-help) if you require help. +To enable this script add the following to a new `~/.bashrc.d/prompt.bash` file: +```bash +$ mkdir -p ~/.bashrc.d +$ nano ~/.bashrc.d/prompt.bash +$ cat ~/.bashrc.d/prompt.bash +``` + ```bash if [[ $- =~ i ]]; then - GIT_PROMPT_PATH=/usr/share/doc/git/contrib/completion/git-prompt.sh - if [[ -r "${GIT_PROMPT_PATH}" ]]; then + GIT_PROMPT_PATH=/usr/share/git-core/contrib/completion/git-prompt.sh + if [[ -r "${GIT_PROMPT_PATH}" ]]; then source "${GIT_PROMPT_PATH}" >&2 else if [[ "$-" == *i* ]]; then @@ -105,7 +172,15 @@ if [[ $- =~ i ]]; then fi ``` -And make sure your `~/.bashrc` file includes: +You may use your preferred editor to create this file; +these lesson materials use the [`nano`](https://www.nano-editor.org/) editor +when a file needs creating or modifying. +This is followed by the `cat` command in the material +to show the file contents after the change. +You do not have to use the `cat` command when following +the lesson material. + +Make sure your `~/.bashrc` file includes: ```bash # User specific aliases and functions @@ -125,27 +200,13 @@ unset rc ### GIT_PROMPT_PATH -Your instructor will let you know if the value of `GIT_PROMPT_PATH` is -different from the path in the example above. -The following paths are for Met Office colleagues. -If you are external to the Met Office please consult +The path in the output above is correct for Met Office systems. +If you are not using Met Office systems please consult your institutions IT services or download your own copy of the `git-prompt.sh` script. Download the latest version from the [Git repository contrib directory](https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh). Ensure the `GIT_PROMPT_PATH` matches where you decide to store the `git-prompt.sh` file. -For Azure Spice, the path in the snippet above is correct: - -```bash -GIT_PROMPT_PATH=/usr/share/doc/git/contrib/completion/git-prompt.sh -``` - -For old Spice: - -```bash -GIT_PROMPT_PATH=/usr/share/doc/git236-2.36.6/contrib/completion/git-prompt.sh -``` - ::: To see the changes to your terminal prompt run: @@ -154,14 +215,16 @@ To see the changes to your terminal prompt run: source ~/.bashrc ``` -::: callout +You might not notice much of a change +until you are in a directory containing a Git repository. + +::: spoiler -### If you have already modified your `PS1` +### If you have already modified your prompt If your `~/.bashrc` file, or any file in the `~/.bashrc.d/` directory, -already modifies your `PS1` command you can -`export PROMPT_COMMAND` instead or seek help from your instructor -on how to merge your current `PS1` command with the one above. +already modifies your prompt using the `PS1` command you can +`export PROMPT_COMMAND` instead. Replace the `export PS1` line with: @@ -178,18 +241,7 @@ export PROMPT_COMMAND=${PROMPT_COMMAND:+"$PROMPT_COMMAND; "}'__git_ps1 "${CONDA_ ::: -::: callout - -### How to get help - -Your instructor will be able to help you with this setup. -At the Met Office please email the -[Science Git Migration Project](mailto:ScienceGitMigrationProjectSupport@metoffice.gov.uk) -and come to a Git & GitHub surgery to receive help. -Details of surgeries can be found on the Science Git Migration Project -SharePoint homepage and MetNets homepage. - -::: +::: spoiler ### Long Terminal Prompts @@ -202,7 +254,7 @@ If adding in your username, `\u`, and hostname, `\h`, makes the terminal prompt too long you can remove the `\u` and or `\h` from the `PROMPT_COMMAND` or `PS1` lines. -#### Add in `PROMPT_DIRTRIM` +#### Trim long directory paths Just before the final `fi` line you may add: @@ -228,13 +280,13 @@ separating your prompt from your terminal commands. Before: ```output -(conda_env) [~/Documents/git-novice]:(branch_name) $ _ +[~/Documents/git-novice]:(branch_name) $ _ ``` After: ```output -(conda_env) [~/Documents/git-novice]:(branch_name) +[~/Documents/git-novice]:(branch_name) $ _ ``` @@ -243,3 +295,5 @@ To see the changes to your terminal prompt run: ```bash source ~/.bashrc ``` + +:::