From 6fa8366b1a9e0ef567818c56b1b0839286cf9e3e Mon Sep 17 00:00:00 2001 From: Dimitrios Theodorakis Date: Tue, 14 Jan 2025 13:58:35 +0000 Subject: [PATCH 1/3] Addresses review comments on Issue 105 --- index.md | 14 ++++- learners/setup.md | 139 ++++++++++++++++++++++++++++++---------------- 2 files changed, 103 insertions(+), 50 deletions(-) diff --git a/index.md b/index.md index 09b620a2fd..8b9cda36b4 100644 --- a/index.md +++ b/index.md @@ -40,10 +40,18 @@ 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. +Learners using either Windows or MacOS should email the support mailbox, +[Science Git Migration Project](mailto:ScienceGitMigrationProjectSupport@metoffice.gov.uk), +if you encounter any problems. diff --git a/learners/setup.md b/learners/setup.md index a4c8dd6930..546a11b516 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,22 +2,66 @@ title: Setup --- -## Pre-workshop Survey +## Lesson Outcomes -Please remember to fill out the pre-workshop survey prior -to the start of the workshop. +This lesson is split into two parts. +Episodes 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-workshop survey](https://forms.office.com/e/XJPJUTn0mp) +prior to the start of the workshop. 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. + +```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. + +```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: @@ -29,10 +73,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 +97,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,13 +108,13 @@ 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 @@ -79,15 +129,22 @@ 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 email the support mailbox, +[Science Git Migration Project](mailto:ScienceGitMigrationProjectSupport@metoffice.gov.uk), +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 @@ -125,27 +182,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,12 +197,15 @@ 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. -### If you have already modified your `PS1` +::: spoiler + +### 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 +already modifies your prompt using the `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. @@ -182,12 +228,11 @@ export PROMPT_COMMAND=${PROMPT_COMMAND:+"$PROMPT_COMMAND; "}'__git_ps1 "${CONDA_ ### 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. +- 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. ::: @@ -202,7 +247,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 +273,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) $ _ ``` From c5c5c614db320d2f9a97c6847d6e5ecd01ffd4b6 Mon Sep 17 00:00:00 2001 From: Dimitrios Theodorakis Date: Wed, 15 Jan 2025 23:08:23 +0000 Subject: [PATCH 2/3] Address review comments --- index.md | 15 +++++++++------ learners/setup.md | 47 +++++++++++++++++++++++------------------------ 2 files changed, 32 insertions(+), 30 deletions(-) diff --git a/index.md b/index.md index 8b9cda36b4..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 @@ -52,6 +56,5 @@ 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. -Learners using either Windows or MacOS should email the support mailbox, -[Science Git Migration Project](mailto:ScienceGitMigrationProjectSupport@metoffice.gov.uk), -if you encounter any problems. +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/learners/setup.md b/learners/setup.md index 546a11b516..c64ae16977 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,10 +2,18 @@ title: Setup --- +## How to get help + +- 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 before the break focus on Git. +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: @@ -33,8 +41,8 @@ And much more! ## Pre-lesson Survey Please remember to fill out the -[pre-workshop survey](https://forms.office.com/e/XJPJUTn0mp) -prior to the start of the workshop. +[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. @@ -63,8 +71,8 @@ git version 2.47.1.windows.1 ### 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 @@ -118,9 +126,10 @@ The GitHub documentation provides [more details about configuring MFA](https://d ### 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 @@ -129,9 +138,8 @@ 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 and email the support mailbox, -[Science Git Migration Project](mailto:ScienceGitMigrationProjectSupport@metoffice.gov.uk), -if you require help. +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: @@ -206,8 +214,7 @@ until you are in a directory containing a Git repository. If your `~/.bashrc` file, or any file in the `~/.bashrc.d/` directory, already modifies your prompt using the `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. +`export PROMPT_COMMAND` instead. Replace the `export PS1` line with: @@ -224,17 +231,7 @@ export PROMPT_COMMAND=${PROMPT_COMMAND:+"$PROMPT_COMMAND; "}'__git_ps1 "${CONDA_ ::: -::: callout - -### How to get help - -- 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. - -::: +::: spoiler ### Long Terminal Prompts @@ -288,3 +285,5 @@ To see the changes to your terminal prompt run: ```bash source ~/.bashrc ``` + +::: From e1b7d3267322a21e9851dc0ffacf35f839ba5b9b Mon Sep 17 00:00:00 2001 From: Dimitrios Theodorakis Date: Mon, 20 Jan 2025 13:12:58 +0000 Subject: [PATCH 3/3] Add version number disclaimer and note about nano and cat command usage --- learners/setup.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/learners/setup.md b/learners/setup.md index c64ae16977..23626bca99 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -53,6 +53,7 @@ for other learners. ### 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 @@ -63,6 +64,7 @@ git version 2.47.0 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 @@ -170,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