Skip to content

Commit

Permalink
reorder the text for better flow
Browse files Browse the repository at this point in the history
  • Loading branch information
@bast
bast committed Sep 17, 2023
1 parent ccdbe98 commit fe8bc3b
Showing 1 changed file with 95 additions and 95 deletions.
190 changes: 95 additions & 95 deletions content/remotes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,10 @@
## From our laptops to the web

We have seen that **creating Git repositories and moving them around is
simple** and that is great.
relatively simple** and that is great.

So far everything was local and all snapshots, branches, and tags are saved under `.git`.
So far, if you only worked in the command line, everything was local and all
snapshots, branches, and tags are saved under `.git`.

If we remove `.git`, we remove all Git history of a project.

Expand All @@ -33,9 +34,26 @@ We will learn how to work with remote repositories in detail in the
[collaborative distributed version control](https://coderefinery.github.io/git-collaborative/) lesson.

In this section we only want to get a taste to prepare us for other lessons
where we will employ GitHub. Our goal is to publish our guacamole recipe on
where we will employ GitHub. Our goal is to publish our exercise guacamole recipe
which we prepared in the previous episodes on
the web. Don't worry, you will be able to remove it afterwards.

````{admonition} If you don't have the recipe repository from previous episodes
Maybe you joined the workshop later or got stuck somewhere? **No problem**!
**If you don't have the recipe repository from previous episodes**, you can
clone our version of the repository using (please **skip this if you have the recipe
repository on your computer already**):
```console
$ git clone https://github.com/coderefinery/recipe-before-merge.git recipe
$ cd recipe
$ git remote remove origin
```
Now you have a repository called `recipe` on your computer with a couple of
commits. Further down we will also clarify what `git clone` does.
````

To store your git data on another server, you use **remotes**.
A remote is a repository on its own, with its own branches
We can **push** changes to the remote and **pull**
Expand All @@ -52,44 +70,86 @@ There are different types of remotes:
commercial site. Many universities have their own private GitLab servers
set up.
- [Bitbucket](https://bitbucket.org) is yet another popular commercial site.
- Another option is [NotABug](https://notabug.org)
- Another option is [NotABug](https://notabug.org).
- We also operate a [Nordic
research software repository
platform](https://coderefinery.org/repository/).
This is GitLab, free for researchers and allows private,
cross-university sharing.

---

## Type-along: Create a new repository on GitHub
% This anchor used for linking from other lessons
(clone-method)=

```{important}
## Authenticating to GitHub: SSH or HTTPS?

Don't do anything yet. We make a choice in the next section, and then
do these steps in the following one.
```
**How does Github know who you are?** This is hard and there are two
options.

* **SSH** is the classic method, using Secure Shell remote connection
keys.
* **HTTPS** works with the **Git Credential Manager**, which is an
extra add-on that works easily in Windows and Mac.

Read how to install them from the [installation
instructions](https://coderefinery.github.io/installation/ssh/).

Test which one you should use:

`````{tabs}
````{group-tab} SSH
Try this command:
```console
$ ssh -T [email protected]
```
If it returns `Hi USERNAME! You've successfully authenticated, ...`,
then SSH is configured and the following steps will work with the SSH
cloning.
See our [installation
instructions](https://coderefinery.github.io/installation/ssh/) to
set up SSH access.
**From now on, if you know that SSH works, you should always select
SSH as the clone URL from GitHub, or translate the URL to start with
the right thing yourself:** `[email protected]:` (with the trailing
`:`).
````
````{group-tab} HTTPS
Try this command:
```console
$ git config --get credential.helper
```
If this shows something, then the credential manager is probably
configured and HTTPS cloning will work (but you can't verify it until
you try using it).
From now on, **if you know that HTTPS works, you should always select
HTTPS as the clone URL from Github, or translate the URL to start with
the right thing yourself:** `https://github.com/`
````
`````

If you do not have these configured, please watch as we do this episode and you
can check the [installation
instructions](https://coderefinery.github.io/installation/ssh/)
before the next [collaborative Git
lesson](https://coderefinery.github.io/git-collaborative/), where we will need
one of these set up.

---

## Creating a new repository on GitHub

For the rest of this page, we will make a new repository for our
guacamole recipe on GitHub ({ref}`here <index>` we motivate why we demonstrate this
with GitHub),
send our code to it, and then see how
others can get the code from it.

````{admonition} If you don't have the recipe repository from previous episodes
Maybe you joined the workshop later or got stuck somewhere? **No problem**!
**If you don't have the recipe repository from previous episodes**, you can
clone our version of the repository using (please **skip this if you have the recipe
repository on your computer already**):
```console
$ git clone https://github.com/coderefinery/recipe-before-merge.git recipe
$ cd recipe
$ git remote remove origin
```
Now you have a repository called `recipe` on your computer with a couple of
commits. Further down we will also clarify what `git clone` does.
````

Make sure that you are **logged into GitHub**.

```{figure} img/creating-using-web/new-top-left.png
Expand Down Expand Up @@ -128,68 +188,6 @@ Once you click the green "Create repository", you will see a page similar to:
What this means is that we have now an empty project with either an HTTPS or an
SSH address: click on the HTTPS and SSH buttons to see what happens.

---

% This anchor used for linking from other lessons
(clone-method)=

## Authenticating to Github: SSH or HTTPS?

**How does Github know who you are?** This is hard and there are two
options.

* **SSH** is the classic method, using Secure Shell remote connection
keys.
* **HTTPS** works with the **Git Credential Manager**, which is an
extra add-on that works easily in Windows and Mac.

Read how to install them from the [installation
instructions](https://coderefinery.github.io/installation/ssh/).

Test which one you should use:

`````{tabs}
````{group-tab} SSH
Try this command:
```console
$ ssh -T [email protected]
```
If it returns `Hi USERNAME! You've successfully authenticated, ...`,
then SSH is configured and the following steps will work with the SSH
cloning.
See our [installation
instructions](https://coderefinery.github.io/installation/ssh/) to
set up SSH access.
**From now on, if you know that SSH works, you should always select
SSH as the clone URL from Github, or translate the URL to start with
the right thing yourself:** `[email protected]:` (with the trailing
`:`).
````
````{group-tab} HTTPS
```console
$ git config --get credential.helper
```
If this shows something, then the credential manager is probably
configured and HTTPS cloning will work (but you can't verify it until
you try using it).
From now on, **if you know that HTTPS works, you should always select
HTTPS as the clone URL from Github, or translate the URL to start with
the right thing yourself:** `https://github.com/`
````
`````

If you do not have these configured, please watch as we do this episode and you
can check the [installation
instructions](https://coderefinery.github.io/installation/ssh/)
prepare before the next [collaborative Git
lesson](https://coderefinery.github.io/git-collaborative/), where we will need
one of these set up.


---

## Pushing our guacamole recipe repository to GitHub
Expand All @@ -207,7 +205,7 @@ We now want to try the second option that GitHub suggests:
need to replace the "USER" part and possibly also the repository name**):


`````{tabs}
`````{tabs}
````{group-tab} SSH
See above for if SSH is the right option for you.
```console
Expand All @@ -220,12 +218,13 @@ We now want to try the second option that GitHub suggests:
$ git remote add origin https://github.com/USER/recipe.git
```
````
`````
`````

```console
$ git branch -M main
$ git push -u origin main
```
Then:
```console
$ git branch -M main
$ git push -u origin main
```

The meaning of the above lines:
- Add a remote reference with the name "origin"
Expand Down Expand Up @@ -309,12 +308,13 @@ $ git clone https://github.com/user/recipe.git myrecipe
`````

What just happened? **Think of cloning as downloading the `.git` part to your
computer**. After downloading the `.git` part the branch pointed to by HEAD is
computer**. After downloading the `.git` part, the default branch (the branch pointed to by HEAD) is
automatically checked out.

```{keypoints}
- A repository can have one or multiple remotes (we will revisit these later).
- Local branches often track remote branches.
- A remote serves as a full backup of your work.
- We'll properly learn how to use these in the [Collaborative Git lesson](https://coderefinery.github.io/git-collaborative/).
- We'll properly learn how to use these in the
[collaborative distributed version control](https://coderefinery.github.io/git-collaborative/).
```

0 comments on commit fe8bc3b

Please sign in to comment.