Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Addresses review comments on Issue 105 #106

Merged
merged 3 commits into from
Jan 20, 2025
Merged

Addresses review comments on Issue 105 #106

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6fa8366
Addresses review comments on Issue 105
astroDimitrios Jan 14, 2025
c5c5c61
Address review comments
astroDimitrios Jan 15, 2025
e1b7d32
Add version number disclaimer and note about nano and cat command usage
astroDimitrios Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:[email protected]),
if you encounter any problems.
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
139 changes: 92 additions & 47 deletions learners/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
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.
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
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
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
```

### 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]
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
### 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:
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
Expand All @@ -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 <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 +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)
Expand All @@ -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).

astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
### Passkeys

Expand All @@ -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:[email protected]),
if you require help.
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved
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
```
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved

```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 Down Expand Up @@ -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:
Expand All @@ -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.
astroDimitrios marked this conversation as resolved.
Show resolved Hide resolved

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

:::

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

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

Expand Down