Mentions légales du service

Skip to content
Snippets Groups Projects
Commit c7203ea5 authored by MALANDAIN Mathias's avatar MALANDAIN Mathias
Browse files

Fix a lot of details up to (and incl.) Section 5

parent 4634cded
Branches
No related tags found
1 merge request!1Changes after Sébastien Gilles' review
......@@ -19,7 +19,7 @@ Among its advantages, you should remember that Git:
This might look like complete overkill for the development of researchware, but it is very useful in this context for several reasons:
* It makes it possible to ***control what is merged in the main version of the codebase*** (and ensure that this main version always works, as we shall see).
* It provides a very convenient ***tagging system***, so that the exact version of the codebase that was used for providing numerical results in scientific articles can be easily retrieved (and you may even go further by providing stable exxecution environments...).
* It provides a very convenient ***tagging system***, so that the exact version of the codebase that was used for providing numerical results in scientific articles can be easily retrieved (and you may even go further by providing stable execution environments...).
* The use of ***Git tools*** such as GitLab makes it possible to ensure long-term backups of codes developed by permanent and non-permanent members alike.
# GitLab {#gitlab}
......@@ -29,9 +29,9 @@ GitLab is a **software development platform** that relies on Git for providing h
A lot of features provided by GitLab are incredibly useful on a day-to-day basis, among others:
* A very convenient ***issue and bug tracking*** for clear and efficient communication and collaboration;
* A very convenient ***issue and bug tracking*** system for clear and efficient communication and collaboration;
* A ***fine handling of permissions and code review***: you can control who can write to each branch of the project, and under which conditions a feature can be merged into the main version of the codebase (which tests should be run, how many people should review and approve the changes, and so on);
* Easy-to-use ***CI/CD pipelines***: Continuous Integration makes it possible to thoroughly test your code before merging it in the main version, and Continuous Delivery provides you with the possibility to automatically deploy your software for your collaborators to use
* Easy-to-use ***CI/CD pipelines***: Continuous Integration makes it possible to thoroughly test your code before merging it in the main version, and Continuous Delivery provides you with the possibility to automatically deploy your software for your collaborators to use.
A lot of other Git-based development platforms exist (GitHub, Gitea, Bitbucket, to name a few), but it so happens that Inria hosts two instances of GitLab, at `gitlab.inria.fr` and `gitlab-int.inria.fr`. Everything on these instances is hosted on Inria's own servers, which guarantees that your code is safe.
......
......@@ -64,7 +64,7 @@ sudo port install git
If you really love your standalone installers, both 32-bit and 64-bit installers are provided [here](https://git-scm.com/download/win).
There is another option that I would warmly recommend, as it will likely save you several other times in the future: [Scoop](https://scoop.sh/#/) is a package manager that you can very easily install and run from the PowerShell, and it installs packages without requiring specific permissions (i.e., no permission popup windows and no inputting passwords every minute). The website provides you with simple instructions for installation; basically just input these two commands in a PowerShell terminal:
There is another option that I would warmly recommend, as it will likely save your life a couple more times in the future: [Scoop](https://scoop.sh/#/) is a package manager that you can very easily install and run from the PowerShell, and it installs packages without requiring specific permissions (i.e., no permission popup windows and no inputting passwords every minute). The website provides you with simple instructions for installation; basically just input these two commands in a PowerShell terminal:
```shell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
......@@ -79,7 +79,7 @@ scoop install git
## Local configuration {#git-config}
Once Git is installed, you may configure it as you want. There are [a lot of options](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration), most of which will not make sense before we delve further into Git. The only thing that is necessary is telling Git your name and e-mail address; this information will not be spread on the Internet and/or sold to companies (this is not Honey!), it will just be written in the metadata of your *commits* (we will be talking about these [later on]({{'/03-linear-git-project#repo' | relative_url }})) so that your collaborators know who contributed which piece of code.
Once Git is installed, you may configure it as you want. There are [a lot of options](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration), most of which will not make sense before we delve further into Git. The only thing that is required is telling Git your name and e-mail address; this information will not be spread on the Internet and/or sold to companies (this is not [Honey](https://www.joinhoney.com/fr/)!), it will just be written in the metadata of your *commits* (we will be talking about these [later on]({{'/03-linear-git-project#repo' | relative_url }})) so that your collaborators know who contributed which piece of code.
Only two commands are needed from the terminal (or the PowerShell terminal for Windows users):
......@@ -88,8 +88,8 @@ git config --global user.name "Your Name"
git config --global user.email "youremail@yourdomain.com"
```
{: .box-info}
Once again, [there are a lot more options to uncover](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration), so that you can customize your Git experience. Most of the options are purely local, including, but not limited to, changing the interface colors, telling Git which tool you want to use for merging different versions of the same file (more on that later!), autoconverting newfile characters (useful for collaborations between Mac/Linux and Windows users)... You can either access those by using `git config` commands, or by directly editing a specific file in a given Git project.
{: .box-note}
Once again, [there are a lot more options to uncover](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration), so that you can customize your Git experience. Most of the options are purely local, including, but not limited to, changing the interface colors, telling Git which tool you want to use for merging different versions of the same file ([more on that later]({{'/03-linear-git-project#conflict' | relative_url }})), autoconverting newfile characters (useful for collaborations between Mac/Linux and Windows users)... You can either access those by using `git config` commands, or by directly editing a specific file in a given Git project.
Great, you have Git on your computer and it's good to go!
......@@ -103,7 +103,7 @@ From now on, every use of the word "GitLab" refers to the `gitlab.inria.fr` inst
This one is easy:
* Go to `gitlab.inria.fr` with your favorite Web browser (even if it is Safari, Chrome or Microsoft Edge, we will let it slide).
* Connect with ILDAP, using your usual CAS username-password pair.
* Connect with iLDAP, using your usual CAS username-password pair.
* Well, that's it. Welcome to GitLab. You should be welcomed with the list of projects hosted on GitLab that you have access to, and you can filter out the ones you did not create yourself by clicking on "Personal". We shall explore the interface pretty soon.
But now, there is a technical hurdle that we should be dealing with. You see, you do not need to log on to the website every time you want to work on a project hosted on GitLab (if this were the case, no one would bother using it). Instead, you "pull" a local copy, on your computer, that you can edit as you wish, and when you are satisfied with your changes, you can "push" the results back. Not everyone can pull a project to their computer, and even less people can push their changes. So, when your computer asks GitLab to pull or push some code, how does GitLab check that you are allowed to do this?
......@@ -126,11 +126,11 @@ If you already have an SSH key that you want to use, you can (of course) skip th
* If you're on Windows: Go to `Settings > App > Optional features` and check that the OpenSSH Client is installed. If it is not, click the `Add a feature` / `+` button, scroll down to OpenSSH Client, and click `Install`. (If you're on Linux or MacOS, you already have it installed.)
* From the Terminal (Linux/MacOS) or the PowerShell (Windows), run either `ssh-keygen -t ed25519` or `ssh-keygen -t rsa -b 4096` (Ed25519 and RSA are two different cryptosystems: Ed25519 is considered safer, but the additional parameter in the second command tells the tool to create a 4096-bit key, which is basically [unbreakable in the foreseeable future](https://security.stackexchange.com/questions/90077/ssh-key-ed25519-vs-rsa)).
* From the Terminal (Linux/MacOS) or the PowerShell (Windows), run either `ssh-keygen -t ed25519` or `ssh-keygen -t rsa -b 4096` (Ed25519 and RSA are two different cryptosystems: Ed25519 is considered safer, but the additional parameter in the second command tells the tool to create a 4096-bit RSA key, which is basically [unbreakable in the foreseeable future](https://security.stackexchange.com/questions/90077/ssh-key-ed25519-vs-rsa)).
* When asked for the full path of the file in which the key should be saved, just press Enter to keep the default path.
* When prompted, enter (twice) a passphrase for your key. You technically can just press Enter so as not to set any passphrase, but this additional layer of security is strongly recommended. (By default, you will have to type this passphrase every time a command such as `git fetch`, `git pull`, `git push`... is run. However, there is a way to alleviate this: see below.)
* Done! You are told where you public and private keys are, plus a long string of seemingly random characters and a weird abstract ASCII art. You may totally ignore these last two things.
* When prompted, enter (twice) a passphrase for your key. You technically can just press Enter so as not to set any passphrase, but this additional layer of security is strongly recommended. (By default, you will have to type this passphrase every time a command such as `git fetch`, `git pull`, `git push`... is run. However, there is a way to alleviate this, as we shall see in a few seconds.)
* Done! You are told where your public and private keys are, plus a long string of seemingly random characters and a weird abstract ASCII art. You may totally ignore these last two things.
* If you are afraid about this "having-to-type-your-huge-passphrase-100-times-a-day" thing, good news are coming your way. What if you were only asked your passphrase once per session? Pretty simple: just type `ssh-add ~/.ssh/<name-of-the-private-key>` (where the name of the private key should be either `id_rsa` or `id_ed25519`). This will definitely make your life easier. You may now say "good night" to your private key: this should be the last time you explicitly use it.
### Giving your public key to GitLab
......@@ -138,9 +138,9 @@ If you already have an SSH key that you want to use, you can (of course) skip th
* Check the contents of your public key (the filename ends with `.pub`, and the whole path to this file is in the output of `ssh-keygen`): you may browse the folder in which it was saved and open the file with any text editor, or display it in your terminal/shell using a command like `more`, or `less`, or `cat`. The key should begin with `ssh-rsa` or `ssh-ed25519` and end with something like `<your_username>@<the_name_of_your_computer>`. Copy the whole think. (The example shown below is an SSH key that I never used and has been erased, for safety reasons.)
![](../assets/img/01-setup/ssh-keygen.jpg){: .mx-auto.d-block :}
> Folder `/Users/mmalanda` is my home folder, also known as `~` by the terminal.
> Folder `/Users/mmalanda` is my home folder, also known as `~` by the terminal. My public key is the whole line that starts with `ssh-ed25519` and ends with `mmalanda@sparemac-az`.
* Log on to GitLab (that's still `gitlab.inria.fr`), click on the round picture on the upper-right corner of the window, then "Edit profile".
* Log on to GitLab (that's still `gitlab.inria.fr`), click on the round picture on the upper-left corner, then "Edit profile".
![](../assets/img/01-setup/ssh-key-1.jpg){: .mx-auto.d-block :}
......@@ -154,7 +154,7 @@ If you already have an SSH key that you want to use, you can (of course) skip th
* Click "Add key", *et voilà*.
* Later on, you will just have to "tell" GitLab that SSH authentication is what you want, instead of HTTPS authentication: this is done when you initialize a fresh Git project or when you clone an already existing project. We will come back to it.
* Later on, you will just have to "tell" GitLab that SSH authentication is what you want, instead of HTTPS authentication: as we shall see pretty soon, this is done when you [initialize a fresh Git project]({{'/02-creating-projects' | relative_url }}) or when you [clone an existing project]({{'/03-linear-git-project#clone' | relative_url }}). We will come back to it.
For the moment, everything is set up. Breathe in. Take a few seconds to appreciate how far you have gone and reconnect with your senses.
......@@ -165,7 +165,7 @@ Breathe out.
{: .box-success}
**VSCode** is a very good code editor with thousands of extensions, including parsers and linters for pretty much every programming language you can think of. It offers a lot of features with a pretty simple and readable interface.
VSCode is by far the most used developer environment tool, with nearly three quarters of respondents to the 2023 Stack Overflow Developer Survey declaring that they use it. Later on, this tutorial will show you how to use Git from VSCode.
VSCode is by far the most used developer environment tool, with nearly three quarters of respondents to the [2024 Stack Overflow Developer Survey](https://survey.stackoverflow.co/2024/technology#1-integrated-development-environment) declaring that they use it. Later on, this tutorial will show you [how to use Git from VSCode]({{'/07-vscode' | relative_url }}).
For the moment, let us configure VSCode for the use of Git... or maybe not: **VSCode knows Git**.
......
......@@ -16,7 +16,7 @@ We will be going through both options, and see various (essentially equivalent)
{: .box-success}
A **project** is pretty much what you think it is. All relevant files for a given software development project (as a first approximation, the contents of the main folder in which you have all the relevant files) are handled together in a project.
As a result, the different versions that will be "remembered" by Git are all snapshots of the entire project. (The way Git actually handles them is way smarter than just storing complete copies of the whole project, so do not worry about storage space. We shall talk about this later on.)
As a result, the different versions that will be "remembered" by Git are all snapshots of the entire project. (The way Git actually handles them is [way smarter]({{'/08-internals#deltas' | relative_url }}) than just storing complete copies of the whole project, so do not worry about storage space.)
Creating a project on GitLab is as simple as clicking a button:
......@@ -39,7 +39,7 @@ There are a few things to unpack there:
{: .box-note}
**Spoiler alert:** The vast majority of projects are created as private projects. When in doubt, make your project private.
* **Initialize repository with a README:** I would advise ***never*** unchecking this box. All it does is create a `README.md` file at the root of the project, and this file will be displayed in all its rendered glory on the corresponding web page. As soon as the project will be accessed by anyone other than yourself, you will want to write some stuff in this file: basic description first, but then, maybe, setup instructions, a short tutorial/example, links to documentation, copyright information, etc. Common practices include adding a few more Markdown files alongside this one:
* **Initialize repository with a README:** When creating a fresh empty project, I would advise never unchecking this box. All it does is create a `README.md` file at the root of the project, and this file will be displayed in all its rendered glory on the corresponding web page. As soon as the project will be accessed by anyone other than yourself, you will want to write some stuff in this file: basic description first, but then, maybe, setup instructions, a short tutorial/example, links to documentation, copyright information, etc. Common practices include adding a few more Markdown files alongside this one:
* `LICENSE.md` where the complete text of the software license is pasted,
* `CHANGELOG.md` where, huh, the change log is provided, and
......@@ -53,7 +53,7 @@ But wait! Before we reach this page, we need to know **where** to create the pro
# Groups {#groups}
GitLab provides you with a *personal namespace*, based on your username. It is the most obvious solution when you want to create a project, but the fact that it is *personal* probably means that it is not the best idea to put everything in here. Plus, well... it would not be a great idea either to put every project in the same place anyways, would it? There are also a lot of limitations on what you can do there, including a strict limit on the number of projects you can create inside it.
GitLab provides you with a *personal namespace*, based on your username. It is the most obvious solution when you want to create a project, but the fact that it is *personal* probably means that it is not the best idea to put everything in here. Also, well... it would not be a great idea either to put every project in the same place anyways, would it? There are also a lot of limitations on what you can do there, including a strict limit on the number of projects you can create inside it.
So... What are our alternatives?
......@@ -64,19 +64,17 @@ Yeah, exactly.
{: .box-success}
**Groups** are exactly what it says on the label. If you have (or *will* have in the foreseeable future) several related projects, you should create a group for them. You can think of a group as a folder for projects... with a sophisticated lock.
"Hey!", you say, "There was this thing about members of the group having automatic access to all projects in the group, right? Why would I want to do that?"
Glad you asked. See, it is true that all members to a group have access to every project in this group: this is what [the GitLab documentation](https://docs.gitlab.com/ee/user/project/members/) calls "inherited membership". With inherited membership, you cannot choose to remove access to a single project: you have to remove the member from the whole group.
You can then invite new members to a group, and they will automatically get access to every project in this group: this is what [the GitLab documentation](https://docs.gitlab.com/ee/user/project/members/) calls "inherited membership". With inherited membership, you cannot choose to remove access to a single project: you have to remove the member from the whole group.
However, you can also add members to individual projects without adding them to the whole group! This is a pretty convenient solution in several contexts, actually:
* For dealing with all pieces of software that are developed in the context of a **large collaborative project**, create a group with a few members (the coordinator(s) + one or two admins sworn to secrecy), then grant access to individual projects as required and carefully set roles for every project (more on that later).
* For gathering all **building bricks of a software suite**, just create each "brick" as a project, all inside the same group with the same members: for each project, each member inherits the role they have in the group itself, so that you only have to deal with who does what *once and for all*.
* For gathering all **building bricks of a software suite** that is developed and maintained as a whole by the same people, just create each "brick" as a project, all inside the same group with the same members: for each project, each member inherits the role they have in the group itself, so that you only have to deal with who does what *once and for all*.
Time for a short summary in a nice green box, don't you think?
{: .box-success}
**Group members** will be given the same role (or permissions, if you will) in all projects in the group. The administrator of the group can then add **project members**: they will be added to projects independently, possibly with different roles in different projects, and they will not be able to see the remaining projects in the group.
**Group members** will be given the same role (or permissions, if you will) in all projects in the group. The administrator can then add **project members**: they will be added to projects independently, possibly with different roles in different projects, and they will not be able to see the remaining private projects in the group.
"Talking about seeing stuff", you say, "what about project visibility? Is group visibility inherited by all projects?" That's a solid question, and the answer is no, thank Gosh! What if you are collaborating with other people for writing both open-source *and* proprietary code? In such cases, the benefits of creating groups would just collapse.
......@@ -89,7 +87,7 @@ Remember that there are three visibility levels: *private*, *internal* and *publ
As a corollary, if at least one of the projects has to be public, you have to create a public group, but other projects can be set to internal, or even private. (People with no access to your private projects will not even be able to know they exist in the first place.)
To sum up, as you go down the chain (from groups to projects), objects can only have their visibility reduced, and members can only have their permissions raised. If you only remember one thing about visibility and permissions, there it is.
To sum up, **as you go down the chain (from groups to projects), objects can only have their visibility reduced, and members can only have their permissions raised**. If you only remember one thing about visibility and permissions, there it is.
And it will be our guideline for the next step, because... Well, what if I work on a huge project, with 100+ pieces of software developed by various members? A single group containing a bazillion projects will not be convenient for anyone.
......@@ -104,9 +102,9 @@ Remember the analogy with folders and subfolders? Yup, here we go again:
In other words, you can create huge tree-shaped architectures of projects. I do not know of any limit for the number of possible subgroups in a group; if you happen to reach it, please (i) tell me, and (ii) sort your life out, this is way too many subgroups, *what are you doing*--
(FYI, there is no creating subgroups in your personal namespace.)
(FYI, there is no creating subgroups in your personal namespace: if you need any sort of hierarchical structure for your projects, even if they are personal, your personal namespace is not fit, and you should create a private group instead.)
As for access, roles and visibility settings, you probably already guessed where we are going. Access can be granted to groups, subgroups or individual projects, and the rules for inheritance are as stated above. Let us highlight this:
As for access, roles and visibility settings, you probably already guessed where we are going. Access can be granted to groups, subgroups or individual projects, and the rules for inheritance are as stated above. Let us highlight this once again:
{: .box-success}
As you go down the hierarchical tree (from group to subgroups to projects), **objects can only have their visibility reduced, and members can only have their role raised**.
......@@ -119,9 +117,9 @@ Sounds pretty abstract, right? Well, let us talk about roles.
This is the part where I lie to your face: **There are 5 different member roles on GitLab.** `</lie>`, I promise.
This is a lie, because a 6th role was added, called "Minimal Access". However, this role cannot be granted at any level and, at the time of writing, [has been buggy for more than two years](https://gitlab.com/gitlab-org/gitlab/-/issues/267996). So, for all intents and purposes, there are 5 different member roles on GitLab. I will try my best to tell you, in less than 500 words, what each of those means. Just scroll down to the next green box if this is too much information for you at this stage, no offence taken.
This is a lie, because a 6th role was added, called "Minimal Access". However, this role cannot be granted at any level and, at the time of writing, [has been buggy for more than three years](https://gitlab.com/gitlab-org/gitlab/-/issues/267996) (the official documentation even provides workarounds now!). So, for all intents and purposes, there are 5 different member roles on GitLab. I will try my best to tell you, in less than 500 words, what each of those means. Just scroll down to the next green box if this is too much information for you at this stage, no offence taken.
* **Guest:** On instances other than `gitlab.com`, a guest on a private project cannot see or download the code. They can basically leave comments, open issues (which is the intended way to report a bug/incident *or request a feature*, so, yeah, kind of a misnomer), and view some very basic metrics. For all intents and purposes, guests are users that can offer feedback. (The guest role does not exist for public projects, because everyone with the right URL has these rights on a public project.)
* **Guest:** On instances other than `gitlab.com`, a guest on a private project cannot see or download the code. They can basically leave comments, [open issues]({{'/04-branches-issues#issues' | relative_url }}) (which is the intended way to report a bug/incident *or request a feature*, so, yeah, kind of a misnomer), and view some very basic metrics. For all intents and purposes, guests are users that can offer feedback. (The guest role does not exist for public projects, because everyone with the right URL has these rights on a public project.)
* **Reporter:** A reporter has all guest permissions, access to the codebase and the project metrics that are provided by GitLab, plus a few permissions related to issues. This list of permissions, along with the name itself, makes me think that reporters are typically non-developers whose main job is to extract basic information about project activity and turn it into colorful graphs to be shown to suit-and-tie executives during bimonthly project follow-up meetings.
* **Developer:** The label here is pretty clear, right? Project developers are the people who write and review code. The "blood, sweat and energy drinks" tier. The larger the project, the more members with this role. (Group developers can also create fresh projects in the group.) However, developers have to play by the rules that are set by the maintainers. To make it clearer, let us see what maintainers can do that developers cannot.
* **Maintainer:** Not only do maintainers have all the permissions that developers have, but they also choose who the developers are, and they draw the line between what any developer can do and what only *they* can do. Adding or removing project members? Their job. (Group members? Nope, only the owner of a group can manage its members.) Specific conditions for code changes to be propagated into some branches? They decide, they enforce. Setting up a robust pipeline for automatic code testing? Their duty. Has the time come for a new release? I don't know, ask *them*. But, you know the saying about great powers and responsibilities. (Was that Jesus Christ or Ulysses S. Grant?) Maintainers are the ones responsible for releasing software that works, for managing issues and incidents, and sometimes for applying ten independent patches to the same codebase in a single day without opening a black hole somewhere in Nevada.
......@@ -195,15 +193,15 @@ I am gonna keep my multigrain baguette recipe private for the moment (visibility
# Pushing existing code on GitLab {#push-code}
There is an alternative to creating empty project, and that is taking existing code that you have on your computer and turning it into a GitLab project. There are many cases that lead to turning local folders into shared projects, a vast majority of which are actually cases of "we should have done it before". Once again, even if you are working by yourself on a piece of code, making it a GitLab project is a good idea for several reasons (backups, complete change history, archiving...).
There is an alternative to creating an empty project, and that is taking existing code that you have on your computer and turning it into a GitLab project. There are many cases that lead to turning local folders into shared projects, a vast majority of which are actually cases of "we should have done it before". Once again, even if you are working by yourself on a piece of code, making it a GitLab project is a good idea for several reasons (backups, complete change history, archiving...).
Assume that, somewhere (**anywhere**) on your computer, you have some folder, let's say a folder called `cornbread` (why not?), that you want to turn into a GitLab project.
Assume that, somewhere (**anywhere**) on your computer, you have some folder, let's say a folder called `cornbread` (why not?), only containing a `README.md` for now, that you want to turn into a GitLab project.
We would indeed like to have this project alongside `multigrain-baguette` on GitLab, that is, in the same subgroup `bread`. Counter-intuitively, we will first have to create an empty project `cornbread`:
![](../assets/img/02-creating-projects/project-from-local-2.jpg){: .mx-auto.d-block :}
Blue button again, and pick the settings you want... but, for convenience, uncheck the "Initialize repository with a README" option this time:
Blue button again, and pick the settings you want... but, for convenience, **uncheck** the "Initialize repository with a README" option this time:
![](../assets/img/02-creating-projects/project-from-local-3.jpg){: .mx-auto.d-block :}
......@@ -217,7 +215,7 @@ This is exactly what you want! *If you want to push **all** the contents of the
**Think about cleaning up your project before pushing it:** you should not push temporary files, local configuration files, and so on. If there are specific files or subfolders that you do not want to push (the `build` or `_build` folders are typical examples), you can choose what you actually want to push. Just replace command `git add .` with several commands of the form `git add path/to/subfolder` or `git add path/to/file`. While the former tells Git to push the whole directory (this is what `.` means), the latter specifies which subfolders and files should be tracked. We will see later on how to [prevent specific files from being added]({{'/05-good-practices#gitignore' | relative_url }}).
{: .box-warning}
If the `-initial-branch` option is not recognized, you have a version of Git that is too old (maybe you installed it a few years ago and forgot to update it). Just update your Git installation and retry.
If the `-initial-branch` option is not recognized, you have a version of Git that is too old (maybe you installed it a few years ago and forgot to update it). Just update your Git installation (the same steps that are used for [a fresh install]({{'/01-setup#git' | relative_url }}) should work) and retry.
Understanding these lines requires knowledge about how Git works, including some dirty details about what Git does behind the curtains. No delving into it right now, but if you're curious:
......@@ -225,7 +223,7 @@ Understanding these lines requires knowledge about how Git works, including some
In short, the Git commands given here basically amount to the following:
* setup the current directory so that it is "Git-ready", and ensure that the name of the default branch is the right one (older projects might have `master` as the name of their default branch, but this was changed in 2020);
* tell Git that this local directory should be linked to the one at the given address (it is exactly the one that is provided to you by *Clone → Clone with SSH* on the project page; **do not use the `https` address instead**: this would require you to use HTTPS authentication on this project, which is way more cumbersome);
* take all the current contents of your local folder (read the box below before continuing) and push them to the GitLab project (plus, the `-u` option tells Git that the remote project to which you just pushed will indeed be the default remote).
* take all the current contents of your local folder (or parts of the contents if you are using one or several `git add some/path` commands instead) and push them to the GitLab project (plus, the `-u` option tells Git that the remote project to which you just pushed will indeed be the default remote).
</div>
Done! Refresh the webpage for your project, and this is what you will see:
......
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -83,7 +83,7 @@ The form you have to fill to actually create the MR is basically the same, excep
1. If the original project is not a private project, that basically means that you are offering some code to a "public" codebase. It can make sense for the community that developed this codebase in the first place to have their word, and what better way of letting them contribute than directly allowing them to commit?
2. This "Contribution guidelines" stuff does not come from nowhere. Well... Turns out there is a reason why GitLab suggests you (and so did I) to create a file named `CONTRIBUTING.md` at the root of any project to which other people might contribute. This link is a pointer to the `CONTRIBUTING.md` file of the project you forked. The closer you follow these guidelines, the higher the chances of your MR being accepted.
{: .box-info}
{: .box-note}
On the other hand, if you want to work from a given snapshot of a project without contributing to it, you may even remove the "fork relationship", by delving into Settings → Advanced -- at your own risk, though, because you will also be missing out on new features, bug fixes, etc. (Once again, you should still make sure that you are complying with the licence(s) of the original project.)
## Closing remarks {#fork-closing}
......
......@@ -36,7 +36,7 @@ The last three lines are more interesting:
* In particular, a branch that I did not know of, called `readme-structure-change`, now exists. This branch now exists in my working copy: a `git switch` to this branch will be lightning fast, because my computer holds all necessary data to switch to this branch.
* In a similar fashion, my computer did not know about tag `checkpoint`; now it does.
{: .box-info}
{: .box-note}
"New content fetched from the repo? Well," you may ask, "where else could it come from? Duh!" First, please do not duh me, thank you, and second, a Git project may very well have several remotes associated to it. Our current use (with GitLab, Github and others) relies on a central repo, but nothing technically prevents you from collaborating on a Git project with several people in a decentralized network... apart from the fact that it is pretty difficult, messy, and no one does that anymore.
Note, however, that `git fetch` may bring you new content, but that it will not delete content that does not exist anymore on the repo.
......@@ -83,7 +83,7 @@ The title of this section is admittedly vague, so let us have a brief look at wh
There are already a lot of very good resources about `git rebase`, probably because it is a command that seems pretty frightening at first, but is actually a very powerful and beautiful command. This is why I will only get to the "why" and the 101 here, before providing you a few links. Also, this is kind of a "pure Git" command, which is not exactly the scope of this tutorial.
{: .box-info}
{: .box-note}
**Rebasing** consists in taking a sequence of commits and moving them somewhere else in the graph of the project.
...okay, well, that's... pretty vague. Could I provide an example? Yeah, sure. Here is the most common use of rebasing:
......@@ -432,7 +432,7 @@ Step 1 remains basically unchanged: cherrypick the commit on the branch to which
Some nice people on Stack Overflow would then advise you to force-push: `git push --force` would overwrite `origin/main` with the contents of your local `main` branch, thus effectively erasing the last commit from public history... You may already know why this is terrible advice in most cases, right? If one or several of your collaborators already pulled the branch as it was seconds ago, with your "wrong" commit on it, then you just made the situation worse for everyone. Once again (for the last time, pinky promise): **Do not rewrite public history unless absolutely necessary.**
{: .box-info}
{: .box-note}
By "absolutely necessary", I basically mean "one of the public commits contains sensitive, private information", and even then, you will have to carefully agree with all members of the project on a specific date at which public history will be rewritten, explicitly tell them what commands they will have to use, make sure that absolutely everyone understands and agrees... Yeah, basically, try and avoid such a terrible situation.
"Okay, so, I cannot just delete my commit, because it is already public. What do I do?" Well, pretty simple: you *revert* it.
......
......@@ -119,6 +119,21 @@ In any case, [please do not hesitate to contact me](mailto:mathias.malandain@inr
----
# Changelog
## September 3rd, 2024
A lot of changes! Thanks to the careful proofreading and insightful advice of Sébastien Gilles, this site got way better.
* New section ["Forks and workflows"]({{'/06-forks' | relative_url }}) gathers information about the three most common Git workflows and how they may or may not fit your projects.
* A lot of small changes and fixes here and there. If you are driven by FOMO, I guess you should reread the whole thing. Sorry about that.
## January 16th, 2024
The first complete version is online!
----
# Future improvements
For any suggestion you may have, please do not hesitate to [send me an e-mail](mailto:mathias.malandain@inria.fr?subject=About%20your%20Git(Lab)%20tutorial).
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment