.. Watlab documentation file, created by Pierre-Yves Gousenbourger on Wed Aug 2, 2023. .. _forge: Setup your SSH-key to join the Forge ==================================== This page will describe how to join the project as a developper, i.e., how to setup your environment to connect to the forge with Git and an SSH key. To learn how to use Git, we recommend the following minimalist tutorial on `W3Schools `_ or a more formal one on the `official Git `_ webpage. Useful resources ---------------- Here are useful links for this Tutorial : - A git `cheat sheet `_ for remembering useful commands when using git in command lines; - The git `website `_ for any troubleshooting; - The gitLab `documentation `_ for `ssh key creation `_; Git is the most common way to code! =================================== Why using Git? -------------- There are multiple answers to this question, but the best one is probably to return a question back to you. Did you ever find yourself in one of the following situations? - You changed something in your code (it can be a big refactoring or just a small change) but suddenly nothing works anymore and you really do not know what you did wrong, so you would love so much to go back to the version before the change, but unfortunately you didn't save any backup. - You work with one (or multiple) colleagues on the same project but years going on, the different versions are totally different programs: you have no idea how to merge them back to a unique version. - You've spent the entire day making major changes to your shared document, you save it, and the day after, everything seems back to normal: your colleague made a tiny change the day before, in the morning, and saved his document when he got internet back. Your pretty work is gone because of a freaking internet shut down at your colleague's side. It isn't your fault nor your colleague's, so life even deny you the right to get angry at someone. - You want to share your project with the world, but you wonder how you can send a USB-key to everyone without bankrupt yourself. If you ever faced one of those situations, you have the answer: with Git, it would never have happened! What is Git? ------------ Git is a versioning program. On the official website, it is said that Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. In other words, Git comes between your changes and the save you make. It works like a nice assistant who takes backup of your current work every now and then, adding stickers and classifiers everywhere so that you can always find previous work when you need it. It also plays as a saveguard avoiding version clash. Conviced? Scroll down! Install useful apps =================== Git --- The first thing you need is to install **Git**. Git is the program that will manage your different versions of the code, allowing you to ``commit``, ``clone``, ``push``, ``pull``, ``merge`` or ``branch`` your code. You can find the installer `on the git website `_. Install it locally (no need for administrator rights). Follow simply the steps. When the installer asks you to add git to your path, say yes. You will then be able to call git from your terminal. Windows Terminal (Windows) - optional ------------------------------------- If you are using Windows, I recommand to install **Windows Terminal** that supports powershell by default. You can download it `there `_. Visual Studio Code ------------------ Visual Studio Code (VS Code) is one of the most appreciated IDE (Integrated Development Editor). Developpers like it because it has many advantages: it colors your code, helps you structure it, integrates a terminal, can be fully configured... but above all, it comes with a monstruous set of extensions, including a built-in Git tool. This tool will help you visualise and handle Git repositories in one clic! You can download **Visual Studio Code** `here `_. To visualize your git history efficiently, you can install the extension named **Git Graph**. Do not forget to add VS Code to your path (if not done at installation). To open a folder in VS Code, there are two ways: 1. Open a terminal, navigate to the folder, then hit .. code-block:: bash code . 2. Open VS Code and clic on **File** > **Open Folder**. Setup your environment ====================== Configure Git ------------- To be able to "sign" your changes later on, you need to let Git know who you are. To do so, open a terminal (anywhere) and hit .. code-block:: bash git config --global user.name "name" where you will replace ``name`` by your name, and then .. code-block:: bash git config --global user.email "email" where you will replace ``email`` by the email your UCLouvain email address. Add an SSH-key to your GitLab account ------------------------------------- Finally, you need a key to let Git communicate with the server. Otherwise, anyone could pretend to be you. There are two ways to communicate with the server: 1. Type your username and password anytime you try to make a change in the code; 2. Use an SSH key that does it for you. This second option is safer and more comfortable, but a little tricky. Follow the guide! An SSH key works on the principle of asymetric cyptographic key: you will share a public key with the Forge of UCLouvain (for encoding messages), and decode the messages with your private key, stored on your computer. For more explanation, invoke `Wikipedia `_ ;-). A complete explanation can be found in the `gitLab documentation `_. Here is a summary if you are lazy. Create the key ^^^^^^^^^^^^^^ First, check if you operating system is equiped with an SSH agent. If yes, it should give you its name and version while hitting .. code-block:: bash ssh --V Check that OpenSSH is installed with an SSH version 6.5 or later. If not, update it. OpenSSH normally comes with Linux, Windows10+ and macOS. To create the key, open a terminal in your home directory (``~/`` in Linux and macOs, ``C:\Users\username\`` in Windows, usually) and hit: .. code-block:: bash ssh-keygen -t ed25519 -C "name_of_my_key" Replace ``name_of_my_key`` with something that reminds you the laptop you are using (ex: "UCLouvain laptop"). This is just a name to help you recognize your keys if you have several ones. Press ``enter`` until a confirmation is displayed. Add the key to GitLab ^^^^^^^^^^^^^^^^^^^^^ Now that your private and public keys have been created, you need to communicate the public one with the Forge of UCLouvain. To do so: 1. Copy the public key stored in ``~\.ssh\id_ed25519.pub`` (Linux and macOS) or ``C:\Users\username\.ssh\id_ed25519.pub``. To do so, you can either open the file with an editor and copy its content, or you can hit one of the following commands: - on macOS: .. code-block:: bash tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy - on Linux (requires the `xclip` package): .. code-block:: bash xclip -sel clip < ~/.ssh/id_ed25519.pub - on Windows (using Windows Terminal with powershell, or Git Bash): .. code-block:: bash cat ~/.ssh/id_ed25519.pub | clip 2. Sign in to the Forge of UCLouvain 3. On the top right, clic on your avatar and select **preferences** 4. On the left bar, select **SSH Keys** 5. In the **key box**, paste your public key (it should start with `ssh-ed25519` and finish with your comment) 6. Click on **Add key**. Test your key ^^^^^^^^^^^^^ You can now verify that your key is correclty settled and working. Nothing more simple. Just open a terminal and hit: .. code-block:: bash ssh -T git@forge.uclouvain.be This command should answer oddly like this: .. code-block:: The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established. ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw. Are you sure you want to continue connecting (yes/no)? This is normal. The Forge is not yet recognized as a trusted host. Just hit ``yes`` to authorize this server. It must then greet you like this: .. code-block:: Welcome to GitLab, @username! .. _clone-the-repository: Clone the repository -------------------- It is now time to type your very first git command. It is named ``clone``. This one is not very important to remember yet crucial. This is the one that allows you to clone the project repository and later on take part to it. 1. Create a folder where you would like to place this project. For instance, a folder placed here (Windows) ``C:\Users\username\projects\``. 2. In the Forge, click on **Clone** and copy the link under **clone with SSH**. 3. Open a terminal and navigate to this folder. 4. Hit the following command .. code-block:: git clone git@forge.uclouvain.be:hydraulics-simulations/watlab.git (note that ``git@forge...`` is exactly the copied link, so you do not have to type it by hand!) Congrat's: now the project has been created. You rock. Quick quick: go in your folder and observe the structure of the **Watlab project**! Possible troubleshooting for UCLouvain users -------------------------------------------- For some reason, it appears that the ``HOME`` path is settled to ``z/`` in some UCLouvain machines running on Windows. A simple way to change that is to 1. Open the start bar 2. Type ``env`` in the search field 3. Click **Modify the environment variables for my account** 4. Click on **New** 5. Fill in the fileds: - **Name:** HOME - **Value:** ``C:\Users\username`` where ``username`` is your Windows username. 6. Hit OK. 7. Hit OK again. Try again to :ref:`clone the repository `. If it still fails, ask Google or contact someone who knows ;-).