diff --git a/docs/pages/git/git-7-working-remotely.md b/docs/pages/git/git-7-working-remotely.md
index 6a2d5ab85c9314afbb1a0a02b7d2734bfa1ca047..45819210f026918720a0e375ef842c23719b40cb 100644
--- a/docs/pages/git/git-7-working-remotely.md
+++ b/docs/pages/git/git-7-working-remotely.md
@@ -26,12 +26,11 @@ Any upload to and from GitHub requires you to authenticate yourself. GitHub
used to allow authentication with your account and password, but this is no
longer the case - using SSH keys is favoured instead. Knowing exactly what these
are is not necessary to get them working, but we encourage you to read the box
-below to learn more about them! GitHub has excellent, platform-specific
-instructions both on how to [generate](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
-and [add](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)
-SSH keys to your account, so please use them before moving on!
+below to learn more about them!
+
+{ width=600px }
-!!! quote "SSH keys and authentication"
+??? quote "SSH keys and authentication details"
Using SSH (Secure Shell) for authentication basically entails setting up a
pair of keys: one private and one public. You keep the private key on your
local computer and give the public key to anywhere you want to be able to
@@ -56,6 +55,30 @@ SSH keys to your account, so please use them before moving on!
you can check out [this website](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process),
which has more in-depth information than we provide here.
+* Generate the key
+
+GitHub has excellent, platform-specific
+instructions on how to [generate](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) SSH keys, but you can follow the instruction below:
+
+!!! Note "Create your SSH key"
+ First check you do not have one already:
+ ```
+ ls ~/.ssh/*.pub
+ ```
+ If you have one, just open the `.pub` file and copy the content.
+ Otherwise type:
+ ```
+ ssh-keygen -t ed25519 -C "your_email@example.com"
+ ```
+ and type enter in the subsequent prompted questions.
+ Then read the content of the `.pub` file located in `~/.ssh/`
+
+* Add the key to github
+
+GitHub has excellent, platform-specific
+instructions on how to [add](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account)
+SSH keys to your account, so please use them before moving on!
+
## Create a remote repository
Log in to your GitHub account and press the *New* button:
@@ -88,8 +111,11 @@ git remote add origin git@github.com:user/git_tutorial.git
```
* Run `git remote -v`. This will show you what remote location is connected to
- your local Git clone. The short name of the default remote is usually
- "*origin*" by convention.
+ your local Git clone.
+
+!!! Info
+ The short name of the default remote is usually
+ "**origin**" by convention.
!!! Note
Make sure you've used an SSH address (*i.e.* starting with `git@github.com`
@@ -98,12 +124,24 @@ git remote add origin git@github.com:user/git_tutorial.git
* We have not yet synced the local and remote repositories, though, we've simply
connected them. Let's sync them now:
+```bash
+git push
+```
+
+!!! question "What happens?"
+
+??? example "Click to show the solution"
+ You get the message `fatal: The current branch master has no upstream branch.` because git does not know to which branch to push the data.
+
+
+We need to tell to the `push` command to push our local history of the `main` branch to the same
+branch on the remote (`origin`).
+
```bash
git push origin main
```
-The `push` command sends our local history of the `main` branch to the same
-branch on the remote (`origin`). Our Git repository is now stored on GitHub!
+Our Git repository is now stored on GitHub!
* Run `git status`. This should tell you that:
@@ -112,10 +150,18 @@ On branch main
nothing to commit, working tree clean
```
-You always need to specify `git push origin main` by default, but you can
-circumvent this by telling Git that you always want to push to
-`origin/main` when you're on your local `main` branch. To do this, use
-the command `git branch --set-upstream-to origin/main`. **Try it out now**.
+!!! Note
+ * You always need to specify `git push origin main` by default, but you can
+ circumvent this by telling Git that you always want to push to
+ `origin/main` when you're on your local `main` branch. To do this, use
+ the command `git branch --set-upstream-to origin/main`.
+ * To avoid having to write git push -u origin new-branch every time you create and push a new branch, you can configure Git to automatically set up the upstream branch when pushing:
+ `git config --global push.autoSetupRemote always`
+
+Configure Git to automatically set up the upstream branch when pushing using the name of the local branch:
+```bash
+git config --global push.autoSetupRemote always
+```
* Now run `git-status` again. You should see that now git additionally tells you
that your local branch is up to date with the remote branch.
@@ -138,14 +184,14 @@ see. Let's try it out!
```markdown
# A Git tutorial
-This repository contains tutorial information related to the **NBIS/ELIXIR** course
-*Tools for Reproducible Research*, specifically the session on using the `git`
-software for version control.
+This repository contains tutorial materials for the **Git course**, designed to help you learn and master *version control*.
+
+`This can be code`
## Links
You can find the latest stable version of the Git tutorial for the course
-[here](https://uppsala.instructure.com/courses/73110/pages/git-1-introduction?module_item_id=367079).
+[here](https://isi.pages.ird.fr/isi-formation-git/).
```
* Add, commit and push these changes to GitHub.
@@ -153,26 +199,29 @@ You can find the latest stable version of the Git tutorial for the course
```bash
git add README.md
git commit -m "Add README.md"
-git push origin main
+git push
```
-You should now be able to see the rendered markdown document, which looks a bit
-different from the text you copied in from above. Note that there are two
-different header levels, which come from the number of hash signs (`#`) used.
-You can also see bold text (which was surrounded by two asterisks), italic
-text (surrounded by one asterisk), in-line code (surrounded by acute accents)
-and a link (link text inside square brackets followed by link address inside
-parentheses).
-
-It is important to add README-files to your repositories so that they are better
-documented and more easily understood by others and, more likely, your future self.
-In fact, documentation is an important part of reproducible research! While the
-tools that you are introduced to by this course are all directly related to
-making science reproducible, you will *also* need good documentation. Make it
-a habit of always adding README-files for your repositories, fully explaining
-the ideas and rationale behind the project. You can even add README-files to
-sub-directories as well, giving you the opportunity to go more in-depth where
-you so desire.
+You should now be able to see the **rendered markdown document**, which looks a bit
+different from the text you copied in from above. There are:
+
+ * two different header levels, which come from the number of hash signs (`#`) used.
+ * bold text (which was surrounded by two asterisks)
+ * italic text (surrounded by one asterisk)
+ * in-line code (surrounded by acute accents)
+ * a link (link text inside square brackets followed by link address inside
+ parentheses).
+
+!!! note
+ It is important to add README-files to your repositories so that they are better
+ documented and more easily understood by others and, more likely, your future self.
+ In fact, documentation is an important part of reproducible research! While the
+ tools that you are introduced to by this course are all directly related to
+ making science reproducible, you will *also* need good documentation. Make it
+ a habit of always adding README-files for your repositories, fully explaining
+ the ideas and rationale behind the project. You can even add README-files to
+ sub-directories as well, giving you the opportunity to go more in-depth where
+ you so desire.
!!! Tip
There are a lot more things you can do with markdown than what we show here.
@@ -181,7 +230,8 @@ you so desire.
!!! Success "Quick recap"
We learned how to connect local Git repositories to remote locations such as
- GitHub and how to upload commits using `git push`. We also learned the
+ GitHub and how to upload commits using `git push`.
+ We also learned the
basics of *markdown* and how it can be used to document Git repositories.
## Browsing GitHub
@@ -304,42 +354,37 @@ a new local branch and add some changes that we'll push as a separate branch to
our remote - you should do this in the original `git_tutorial` repository, so
move back into that directory.
-* Create a new branch named `trimming` and add the `--trim5 5` flag to the
- bowtie2-command part of the `Snakefile`, which should now look like this:
-
-```bash
-bowtie2 --trim5 5 --very-sensitive-local -x $indexBase -U {input.fastq} > {output} 2> {log}
-```
+* Create a new branch named `readme` and add modifications to the README file.
* Add and commit the change to your local repository.
-* Instead of doing what we previously did, *i.e.* merge the `trimming` branch
- into the `main` branch, we'll push `trimming` straight to our remote:
+* Instead of doing what we previously did in the *branching and merging* section, *i.e.* merge the `readme` branch
+ into the `main` branch, we'll push `readme` straight to our remote:
```bash
-git push origin trimming
+git push
```
* Go the repository at GitHub and see if the new branch has appeared. Just above
the file listing click the *Branch* drop-down and select the new branch to
- view it. Can you see the difference in the `Snakefile` depending on which
+ view it. Can you see the difference in the `README` depending on which
branch you choose?
-We now have two branches both locally and remotely: `main` and `trimming`. We
-can continue working on our `trimming` branch until we're satisfied (all the
+We now have two branches both locally and remotely: `main` and `readme`. We
+can continue working on our `readme` branch until we're satisfied (all the
while pushing to the remote branch with the same name), at which point we want
to merge it into `main`.
-* Checkout your local `main` branch and merge it with the `trimming` branch.
+* Checkout your local `main` branch and merge it with the `readme` branch.
* Push your `main` branch to your remote and subsequently delete your local
- `trimming` branch.
+ `readme` branch.
The above command only deleted the local branch. If you want to remove the
branch from the remote repository as well, run:
```bash
-git push origin --delete trimming
+git push --delete readme
```
!!! Success "Quick recap"
diff --git a/docs/pages/git/git-8-conflicts.md b/docs/pages/git/git-8-conflicts.md
index f395157d8281a0477ff53fa5bdc2c7e756ef09f3..cbfac1dc58cead28da0b3293ff42f3bd20a16d92 100644
--- a/docs/pages/git/git-8-conflicts.md
+++ b/docs/pages/git/git-8-conflicts.md
@@ -82,6 +82,27 @@ git merge
Unsurprisingly, the `git merge` command resulted in a conflict. Git tells us
about this and suggests that we should fix the conflicts and commit that.
+!!! note
+ Using the two steps approach (`git fetch` then `git merge`) can be cumbersome.
+ You might prefer to use directly `git pull` that perform both in one command.
+ The first time doing so it will teel you
+ ```
+ hint: You have divergent branches and need to specify how to reconcile them.
+ hint: You can do so by running one of the following commands sometime before
+ hint: your next pull:
+ hint:
+ hint: git config pull.rebase false # merge
+ hint: git config pull.rebase true # rebase
+ hint: git config pull.ff only # fast-forward only
+ hint:
+ hint: You can replace "git config" with "git config --global" to set a default
+ hint: preference for all repositories. You can also pass --rebase, --no-rebase,
+ hint: or --ff-only on the command line to override the configured default per
+ hint: invocation.
+ ```
+ No need to understand the different reconciliation approaches.
+ As default it is good to use `git config pull.rebase false` (History will reflect merges explicitly).
+
* As always, run `git status` to get an overview: you will see that you have
so-called unmerged paths and that the conflicting file is `environment.yml`,
since both modified the same line in this file. To fix a conflict, open the
diff --git a/docs/pages/git/images/ssh.png b/docs/pages/git/images/ssh.png
new file mode 100644
index 0000000000000000000000000000000000000000..439fa5e87a26350599a94a640014b2226459c5e7
Binary files /dev/null and b/docs/pages/git/images/ssh.png differ