@@ -39,7 +39,7 @@ A lot of other Git-based development platforms exist (GitHub, Gitea, Bitbucket,
Everything on `gitlab.inria.fr` and `gitlab-int.inria.fr` is hosted on Inria's own servers, which guarantees that your code is safe!
{: .box-warning}
This is why you should **not** use `gitlab.com` or `github.com` for your software projects!
In most cases, you should **not** use `gitlab.com` or `github.com` for your software projects. If you are only working with specific collaborators, including a few who do not have an Inria account, the Inria instances of GitLab should still be used: you can very simply [invite external collaborators to `gitlab.inria.fr`](https://external-account.inria.fr). The use of external platforms like `gitlab.com` and `github.com` can be envisioned for open-source software, for which external contributions can be expected (...and in that case, you should also probably discuss the legal aspects with the right people at Inria before making any move), but as long as there is no stringent need, you should keep your codebase safe.
It is impossible to overstate how the use of GitLab makes collaborating on a software project easier and faster, and you can learn how to use it **one step at a time**.
@@ -8,6 +8,8 @@ Enough chit-chat, let us delve right into it.
# Installing Git {#git}
There are different ways of installing Git based on the operating system you are using. Once this is done, please ***do not skip [the last subsection]({{'/01-setup#git-config' | relative_url }})***: it is a required configuration step (if you skip it, Git will ask you before you can change the contents of a project).
## Linux-based distributions
All package managers know Git. Here are a few examples:
...
...
@@ -56,16 +58,29 @@ sudo port install git
Standalone installers (both 32-bit and 64-bit) are provided [here](https://git-scm.com/download/win).
## 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.
Only two commands are needed from the terminal (or Powershell for Windows users):
Great, you have Git on your computer and it's good to go!
# Connecting to GitLab {#gitlab}
{: .box-note}
From now on, every use of the word "GitLab" refers to the `gitlab.inria.fr` instance. Things work in a very similar fashion on `gitlab-int.inria.fr`, except that one cannot invite external collaborators there. Other instances, including `gitlab.com`, are not covered here, but they are basically the same tool: you might just have less options on `gitlab.com` as a simple, non-paying user... and your data would be stored on some server somewhere, potentially accessible by Gosh-knows-whom.
From now on, every use of the word "GitLab" refers to the `gitlab.inria.fr` instance. Things work in a very similar fashion on `gitlab-int.inria.fr`, except that one cannot [invite external collaborators](https://external-account.inria.fr/) there. Other instances, including `gitlab.com`, are not covered here, but they are basically the same tool: you might just have less options on `gitlab.com` as a simple, non-paying user... and your data would be stored on some server somewhere, potentially accessible by Gosh-knows-whom.
## Accessing the website
This one is easy:
* Go to `gitlab.inria.fr` with your favorite Web browser (even if it is Safari or Microsoft Edge, we will let it slide).
* 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.
* 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.
...
...
@@ -92,8 +107,9 @@ If you already have an SSH key that you want to use, you can (of course) skip th
* 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)).
* 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. (However, you will have to type this passphrase every time you have to communicate with GitLab from your computer, that is, every time a command such as `git fetch`, `git pull`, `git push`... is run. Thus, I would advise against setting a 100-character passphrase for your SSH key. Your CAS password, on the other hand...)
* 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.
* If you are afraid about this "having-to-type-your-huge-passphrase-100-ties-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.
@@ -55,7 +55,7 @@ But wait! Before we reach this page, we need to know **where** to create the pro
Back when paper existed (aaaah, good ol' times), we organized our actual, physical files in folders, themselves sorted in different drawers and file cabinets. This basic organization was projected into our computers, with, once again, files in folders, but this time, we could have any (limited, but already potentially huge) tree-like hierarchy of folders ans subfolders. Would you have any trust in a tool designed to manage your software projects that just throws all these projects on the same pile?
Yeah, exacty.
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.
...
...
@@ -205,7 +205,10 @@ Once your project is created, you are welcomed with instructions on how to actua
This is exactly what you want! Just follow these instructions, and the contents of the folder you `cd` into will be pushed into your fresh GitLab project.
This is exactly what you want! *If you want to push **all** the contents of the local folder you `cd` into*, just follow these instructions, and the whole folder will be pushed into your fresh GitLab project.
{: .box-warning}
**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.
...
...
@@ -216,7 +219,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 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 (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).
</div>
Done! Refresh the webpage for your project, and this is what you will see:
