diff --git a/.gitignore b/.gitignore index e6b97f91..2ce29f56 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ _build/ build/ .ipynb_checkpoints /venv* +/.venv/ .jupyter_cache jupyter_execute /content/__pycache__/ diff --git a/content/configuration.md b/content/configuration.md index 7b29ab74..8ce426c4 100644 --- a/content/configuration.md +++ b/content/configuration.md @@ -6,11 +6,11 @@ We have a longer version of this in the [installation instructions](https://coderefinery.github.io/installation/git-in-terminal/). But for clarity, we will review the most important parts here. -You don't need to set these if you work only through the GitHub web interface. +You don't need to set these if you work only through the GitHub or GitLab web interface. If you use VS Code or other editors or integrated development environments, the editor might prompt you to set these up. If you use RStudio, you can carry out the configuration in RStudio (see the RStudio tab in the section [Authenticating -to GitHub](https://coderefinery.github.io/git-intro/configuration/#authenticating-to-github-ssh-or-https-or-vs-code) +to GitHub or GitLab](clone-method) below). These configuration settings are saved in a file called `.gitconfig` in your @@ -34,11 +34,17 @@ $ git config --global user.name "Your Name" $ git config --global user.email yourname@example.com ``` -For the email address we recommend to use the one you use for your GitHub account. -If you prefer to not use it, you can instead use -`YOUR_GITHUB_USERNAME@users.noreply.github.com` as the email address (replace `YOUR_GITHUB_USERNAME`). -This means that nobody can write to this email address, but GitHub will still -be able to connect your contributions with your GitHub account. +For the email address we recommend using the one associated with your GitHub +or GitLab account. If you prefer not to expose your personal email address, +you can instead use the privacy-preserving no-reply address provided by the +service: + +- GitHub: Copy the exact address shown in your [email settings](https://github.com/settings/emails). +- GitLab: In your profile settings, select **Use a private email** as the commit email and copy the generated address. + +The address may contain an account-specific ID, username, or other details, so +do not try to construct it yourself. This allows the service to connect your +contributions with your account without exposing your personal email address. Note that these can, in theory, be anything: this is just data, not a registration or identity requirement. @@ -84,9 +90,9 @@ to set other editors, or do a web search for "git set editor to % This anchor used for linking from other lessons (clone-method)= -## Authenticating to GitHub: SSH or HTTPS or VS Code or RStudio? +## Authenticating to GitHub or GitLab: SSH or HTTPS or VS Code or RStudio? -**How does GitHub know who you are?** We discuss here four options: +**How does the hosting service know who you are?** We discuss here four options: - **SSH** is the classic method, using [Secure Shell Protocol](https://en.wikipedia.org/wiki/Secure_Shell) remote connection keys. @@ -104,7 +110,9 @@ Test which one you should use: :::::{tabs} ::::{group-tab} Command line: SSH - Try this command: + Try one of these commands, depending on where your repository is hosted: + + **GitHub:** ```console $ ssh -T git@github.com ``` @@ -113,13 +121,21 @@ Test which one you should use: then SSH is configured and the following steps will work with the SSH cloning. + **GitLab:** + ```console + $ ssh -T git@gitlab.com + ``` + + If it returns `Welcome to GitLab, @USERNAME!`, then SSH is configured + and the following steps will work with SSH cloning. + + From now on, **if you know that SSH works, select SSH as the clone URL + from the service hosting your repository.** GitHub URLs start with + `git@github.com:` and GitLab URLs start with `git@gitlab.com:`. + 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:** `git@github.com:` (with the `:`). :::: ::::{group-tab} Command line: HTTPS @@ -133,32 +149,32 @@ Test which one you should use: 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/` + HTTPS as the clone URL from your hosting service, or translate the URL + to start with the right thing yourself:** `https://github.com/` or + `https://gitlab.com/` :::: ::::{group-tab} VS Code - VS Code has its own authentication method and the editor will guide you - through the process. If you are using VS Code, you can skip the SSH and - HTTPS checks. + VS Code has its own authentication method for GitHub and GitLab + integrations, and the editor or its extension will guide you through the + process. If you are using VS Code, you can skip the SSH and HTTPS checks. From now on, you should **select HTTPS as the clone URL from - GitHub, or translate the URL to start with the right thing - yourself:** `https://github.com/` + GitHub or GitLab, or translate the URL to start with the right thing + yourself:** `https://github.com/` or `https://gitlab.com/` - If you don't want VS Code to be connected to your GitHub account, + If you don't want VS Code to be connected to your GitHub or GitLab account, set up and use the SSH method instead. :::: ::::{group-tab} RStudio See our [installation instructions](https://coderefinery.github.io/installation/ssh/) - for how to run the GitHub configuration directly in RStudio using commands - in the R package `usethis` and how to test that everything worked. These - instructions use **HTTPS** for authentication. + for how to configure SSH or HTTPS authentication. In RStudio, these steps + can be run in the Terminal tab of the console panel. After the configuration, you should **select HTTPS as the clone URL from - GitHub, or translate the URL to start with the right thing - yourself:** `https://github.com/` + GitHub or GitLab, or translate the URL to start with the right thing + yourself:** `https://github.com/` or `https://gitlab.com/` To set your default branch name in Git to `main` in RStudio, run diff --git a/content/img/gitlab/merging-change-branches-annotated.png b/content/img/gitlab/merging-change-branches-annotated.png new file mode 100644 index 00000000..a519b353 Binary files /dev/null and b/content/img/gitlab/merging-change-branches-annotated.png differ diff --git a/content/img/gitlab/merging-change-branches-original.png b/content/img/gitlab/merging-change-branches-original.png new file mode 100644 index 00000000..9bc1a81b Binary files /dev/null and b/content/img/gitlab/merging-change-branches-original.png differ diff --git a/content/img/gitlab/merging-choose-target-branch-annotated.png b/content/img/gitlab/merging-choose-target-branch-annotated.png new file mode 100644 index 00000000..3318c571 Binary files /dev/null and b/content/img/gitlab/merging-choose-target-branch-annotated.png differ diff --git a/content/img/gitlab/merging-delete-branch-annotated.png b/content/img/gitlab/merging-delete-branch-annotated.png new file mode 100644 index 00000000..51e6938e Binary files /dev/null and b/content/img/gitlab/merging-delete-branch-annotated.png differ diff --git a/content/img/gitlab/merging-delete-branch-original.png b/content/img/gitlab/merging-delete-branch-original.png new file mode 100644 index 00000000..8621f8a1 Binary files /dev/null and b/content/img/gitlab/merging-delete-branch-original.png differ diff --git a/content/img/gitlab/merging-delete-source-branch-annotated.png b/content/img/gitlab/merging-delete-source-branch-annotated.png new file mode 100644 index 00000000..68a285b8 Binary files /dev/null and b/content/img/gitlab/merging-delete-source-branch-annotated.png differ diff --git a/content/img/gitlab/merging-navigate-branch-annotated.png b/content/img/gitlab/merging-navigate-branch-annotated.png new file mode 100644 index 00000000..3a8e27a5 Binary files /dev/null and b/content/img/gitlab/merging-navigate-branch-annotated.png differ diff --git a/content/img/gitlab/merging-navigate-branch-original.png b/content/img/gitlab/merging-navigate-branch-original.png new file mode 100644 index 00000000..60b621db Binary files /dev/null and b/content/img/gitlab/merging-navigate-branch-original.png differ diff --git a/content/img/gitlab/merging-open-merge-request-annotated.png b/content/img/gitlab/merging-open-merge-request-annotated.png new file mode 100644 index 00000000..752a6bea Binary files /dev/null and b/content/img/gitlab/merging-open-merge-request-annotated.png differ diff --git a/content/img/gitlab/sharing-create-project-annotated.png b/content/img/gitlab/sharing-create-project-annotated.png new file mode 100644 index 00000000..4739a8b9 Binary files /dev/null and b/content/img/gitlab/sharing-create-project-annotated.png differ diff --git a/content/img/gitlab/sharing-create-project-original.png b/content/img/gitlab/sharing-create-project-original.png new file mode 100644 index 00000000..02ee7bd5 Binary files /dev/null and b/content/img/gitlab/sharing-create-project-original.png differ diff --git a/content/img/gitlab/sharing-projects-annotated.png b/content/img/gitlab/sharing-projects-annotated.png new file mode 100644 index 00000000..2b8dcddb Binary files /dev/null and b/content/img/gitlab/sharing-projects-annotated.png differ diff --git a/content/img/gitlab/sharing-projects-original.png b/content/img/gitlab/sharing-projects-original.png new file mode 100644 index 00000000..f6ad8af5 Binary files /dev/null and b/content/img/gitlab/sharing-projects-original.png differ diff --git a/content/img/gitlab/sharing-upload-file-annotated.png b/content/img/gitlab/sharing-upload-file-annotated.png new file mode 100644 index 00000000..444edbed Binary files /dev/null and b/content/img/gitlab/sharing-upload-file-annotated.png differ diff --git a/content/img/gitlab/sharing-upload-file-original.png b/content/img/gitlab/sharing-upload-file-original.png new file mode 100644 index 00000000..896f234f Binary files /dev/null and b/content/img/gitlab/sharing-upload-file-original.png differ diff --git a/content/merging.md b/content/merging.md index 66bbbe2a..c6b81a17 100644 --- a/content/merging.md +++ b/content/merging.md @@ -6,8 +6,8 @@ means that we have to somehow combine the changes later. In this part we will practice this: {term}`merging`. :::{objectives} -- Understand that on GitHub merging is done through a {term}`pull request`. Think of it as a **change proposal**. -- Create and merge a pull request within your own repository. +- Understand that on GitHub merging is done through a {term}`pull request`. The equivalent on GitLab is called a {term}`merge request`. Think of it as a **change proposal**. +- Create and merge a pull/merge request within your own repository. - Understand (and optionally) do the same across repositories, to contribute to the {term}`upstream` public repository. ::: @@ -97,6 +97,18 @@ We provide basic hints. You should refer to the solution as needed. ::: :::: +::::{group-tab} GitLab +:::{exercise} Exercise: Merging branches with merge requests +We assume that you have created a new branch with a recipe. + +1. Navigate to your branch. +2. Click "Create merge request" in the upper right in the branch view. +3. Provide a title and a description for the merge request. Make sure to merge with your own repository: click "Change branches", choose your own fork as the target project, and choose its `main` branch as the target branch. +4. Create the merge request by clicking "Create merge request". +5. Merge the merge request. +6. Find out which branches are merged and thus safe to delete. +:::: + ::::{group-tab} Local (VS Code, Command line, RStudio) When working locally, it's easier to merge branches: we can just do @@ -149,6 +161,15 @@ On GitHub make sure you are on the branch you want to merge **from**: ::: :::: +::::{group-tab} GitLab +On GitLab make sure you are on the branch you want to merge **from**: + :::{figure} img/gitlab/merging-navigate-branch-annotated.png + :alt: Screenshot on Gitlab where we navigate to the branch we wish to merge. + :width: 80% + :class: with-border + ::: +:::: + ::::{group-tab} VS Code Remember, you need to switch to the `main` branch, the branch we want to merge **to**. This is different from the GitHub path. @@ -186,6 +207,14 @@ branches together. We start the process of making one. ::: :::: +::::{group-tab} GitLab + :::{figure} img/gitlab/merging-open-merge-request-annotated.png + :alt: Screenshot on GitLab where we get to the merge request process. + :width: 80% + :class: with-border + ::: +:::: + ::::{group-tab} VS Code It is possible to open pull requests from the editor, but we don't cover that here. @@ -233,6 +262,27 @@ Things to check: ::: :::: +::::{group-tab} GitLab +Things to check: +- Target project: this should be your own +- Title: make it descriptive +- Description: make it informative +- Scroll down to see commits: are these the ones you want to merge? +- Scroll down to see the changes: are these the ones you want to merge? + + :::{figure} img/gitlab/merging-change-branches-annotated.png + :alt: Screenshot on GitLab where we change branches. + :width: 80% + :class: with-border + ::: + + :::{figure} img/gitlab/merging-choose-target-branch-annotated.png + :alt: Screenshot on GitLab where we change target branch. + :width: 80% + :class: with-border + ::: +:::: + ::::{group-tab} VS Code If you are working locally, continue to step 5. :::: @@ -248,10 +298,10 @@ If you are working locally, continue to step 5. ::::: -### (4) Create the pull request +### (4) Create the pull/merge request -We actually create the pull request. Don't forget to navigate to the Network -view after opening the pull request. Note that the changes proposed in the +We actually create the pull/merge request. Don't forget to navigate to the Network +view after opening the pull/merge request. Note that the changes proposed in the pull request are not yet merged. :::::{tabs} @@ -264,6 +314,10 @@ when collaborating with others. It allows you to open a pull request that is not ready to be merged yet, but you want to show it to others and get feedback. :::: +::::{group-tab} GitLab +Click on the black button "Create merge request". Below the title of the merge request you can choose "Mark as draft". This will be useful when collaborating with others. It allows you to open a merge request that is not ready to be merged yet, but you want to show it to others and get feedback. +:::: + ::::{group-tab} VS Code It is possible to create pull requests from the editor, but we don't cover that here. @@ -301,6 +355,10 @@ After merging, verify the network view. Also navigate then to your "main" branch and check that your new recipe is there. :::: +::::{group-tab} GitLab +Review the merge request (commits and changes) and click "Merge". When merging, you can choose to delete the source branch at the same time. +:::: + ::::{group-tab} VS Code Just like with the command line, when we merge we modify our *current* branch. Verify you are on the `main` branch. @@ -373,6 +431,16 @@ In the overview we can see that it has been merged and we can delete it: ::: :::: +::::{group-tab} GitLab +One way to delete the branch is to check off "delete source branch" before merging. If you forgot to do so, you can delete the branch afterwards. Click on "branches" and find the branch that you want to delete. Click on the three dots to the right and choose "Delete branch". + :::{figure} img/gitlab/merging-delete-source-branch-annotated.png + :alt: Screenshot on Gitlab where we delete branch. + :width: 80% + :class: with-border + ::: +:::: + + ::::{group-tab} VS Code From the Source Control sidebar → the three dots (as before) → Branch → Delete Branch. Select the branch name to delete. :::: @@ -425,6 +493,12 @@ merge the pull request. We can then together review and browse the pull request. :::: +::::{group-tab} GitLab +Now you know how to create branches and open a merge request. Try to open a merge request with a new change but this time set the target project to the upstream repository. This means that you send a merge request across repositories: from your own fork to the original repository. + +Another thing that is different is that you might not have permission to merge the merge request. This means that someone with permission needs to review and approve your merge request. +:::: + ::::{group-tab} VS Code Not described. We will return to this in the [collaborative Git lesson](https://coderefinery.github.io/git-collaborative/). @@ -470,7 +544,7 @@ How to create a conflict (please try this in your own time *and just watch now*) - Now try to merge the new branch to `main`. You will get a conflict. How to resolve conflicts: -- On GitHub, you can resolve conflicts by clicking on the "Resolve conflicts" +- On GitHub and GitLab, you can resolve conflicts by clicking on the "Resolve conflicts" button. This will open a text editor where you can choose which changes to keep. Make sure to remove the conflict markers. diff --git a/content/reference.md b/content/reference.md index 80a5cce8..7c3305bf 100644 --- a/content/reference.md +++ b/content/reference.md @@ -114,6 +114,9 @@ merging Bringing changes from one branch into another, either as a noun or verb. +merge request + A GitLab concept equivalent to {term}`pull request` on GitHub. + VS Code A text editor and development environment by Microsoft. It's quite popular, partly because it is powerful and easy to use. [VS diff --git a/content/sharing.md b/content/sharing.md index dcf721aa..ba9f39c6 100644 --- a/content/sharing.md +++ b/content/sharing.md @@ -35,13 +35,17 @@ From a bunch of files to a local repository which we then share on GitHub. 2. Turn this new directory into a Git repository. 3. Share this repository on GitHub (or GitLab, since it really works the same). -We offer **three different paths** of how to do this exercise. +We offer **five different paths** of how to do this exercise. * Via **GitHub web interface**: easy and can be a good starting point if you are completely new to Git. +* Via **GitLab web interface**: similar to the GitHub path; create a blank + project, initialize it with a README file, and upload your project files. * **VS Code** is quite easy, since VS Code can offer to create the GitHub repositories for you. * **Command line**: you need to create the repository on GitHub and link it yourself. +* **RStudio**: initialize Git for your project, connect it to an empty + repository on GitHub or GitLab, and use RStudio's Push and Pull buttons. ::::{tabs} @@ -80,6 +84,33 @@ Click on the "+" symbol and then on "Upload files". ``` ::: +:::{group-tab} GitLab +**Create a repository on GitLab** +First log in to GitLab, then follow the screenshots and descriptions below. +```{figure} img/gitlab/sharing-projects-annotated.png +:alt: Screenshot on GitLab where we start creating a new project. +:width: 100% +:class: with-border +``` +After clicking "Create project", click "Create blank project". + +```{figure} img/gitlab/sharing-create-project-annotated.png +:alt: Screenshot on GitLab where we create a new project. +:width: 100% +:class: with-border +``` +*Choose a project name, add your username under "project URL", choose "Public", and add a README file. Finally "Create project".* + +**Upload your files** +Now that the project is created, you can upload your files: +```{figure} img/gitlab/sharing-upload-file-annotated.png +:alt: Screenshot on GitLab where we upload files. +:width: 100% +:class: with-border +``` +::: + + :::{group-tab} VS Code In VS Code it only takes few clicks.