Skip to content

Commit

Permalink
markdown source builds
Browse files Browse the repository at this point in the history 
Auto-generated via `{sandpaper}`
Source  : 909f4e9
Branch  : main
Author  : Dimitrios Theodorakis <[email protected]>
Time    : 2025-01-20 13:30:27 +0000
Message : MetOffice#106 Addresses review comments on Issue MetOffice#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
  • Loading branch information
@actions-user
actions-user committed Jan 20, 2025
1 parent 0725004 commit 858da6b
Show file tree
Hide file tree
Showing 3 changed files with 134 additions and 69 deletions.
23 changes: 17 additions & 6 deletions index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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).
4 changes: 2 additions & 2 deletions md5sum.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"
176 changes: 115 additions & 61 deletions setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:[email protected]).

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
Expand All @@ -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 <https://github.com> and follow the "Sign up" link at the top-right of the window.
2. Follow the instructions to create an account.
Expand All @@ -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)
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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:

Expand All @@ -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:[email protected])
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

Expand All @@ -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:

Expand All @@ -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)
$ _
```

Expand All @@ -243,3 +295,5 @@ To see the changes to your terminal prompt run:
```bash
source ~/.bashrc
```

:::

0 comments on commit 858da6b

Please sign in to comment.