Changes

Boman Romain · 2c8ad9b9
--- a/git.md
+++ b/git.md
 Git is a "version control system". It is used by developers to keep track of the successive changes in their code (all the versions are stored in a "repository" with a version number). Git also provides a team of developers with various tools which help them solve problems related to concurrent modifications of the code.
 Git is thus a **professional way to share code between developers**.
 ## Install git (macOS)
 Open a terminal and type `git`. If git is not installed yet, the system will ask you if you want to install the developer tools. 
 ```
 xcode-select: note: no developer tools were found at '/Applications/Xcode.app',
 requesting install. Choose an option in the dialog to download the command line 
 developer tools.
 ```
 Agree and proceed with the installation.
 ## Install git (Linux)
 On the [CECI clusters](http://www.ceci-hpc.be/), a recent version of git is available as soon as your are connected to the master node.
 On your own **Linux** PC, you can install git with the package manager. For example, with Ubuntu:
 ```
 sudo apt install git
 ```
-Git will open a text editor when running certain commands such as `git merge` or `git commit`. The default editor is [vim](https://www.vim.org/) which is rather difficult to use. If you don't plan to use vim, set the environment variable `EDITOR` to the name of your preferred editor by adding the following line at the end of your `\~/.bashrc` file:
+Git will open a text editor when running certain commands such as `git merge` or `git commit`. The default editor is [vim](https://www.vim.org/) which is rather difficult to use. If you don't plan to use vim, set the environment variable `EDITOR` to the name of your preferred editor by adding the following line at the end of your `~/.bashrc` file:
 ```
 export EDITOR=XXXX
 ```
 where `XXXX` is the name of the editor. It could be `nano`, `emacs`, or any other user-friendly text editor available on Linux. You can install nano, or emacs with the a command similar to:
 ```
 sudo apt install nano
 ```
 If you work on **Windows**, git is not provided by Microsoft with the OS. You must install it before the next steps (see next section).
 ## Download git (Windows only)
 Download the latest version of git from the website: https://git-scm.com/
 ## Install git (Windows only)
 Double-click on the installer, then follow the instructions. Choose the default options except for the default editor which is configured for "vim" (an old type of editor which is rather difficult to use).
 ![](git_editor.png)
 Choose one editor that you know well instead of vim (e.g. NotePad or [NotePad++](https://notepad-plus-plus.org/) on Windows).
 ## Configure git (Windows/Linux/macOS)
 On Windows, you can use "git" by right-clicking on a folder in the windows explorer and by running "Git Bash Here". Git is also available in any command-line window (Run "cmd", then type `git` in the terminal).
 On the other systems (Linux/macOS), open a terminal.
 Then, on any system (Windows/linux/macOS), type these 2 commands:
 ```
 git config --global user.name "Your Name"
 git config --global user.email "your_email@student.uliege.be"
 ```
 Git must know your name and e-mail address. All your personal work will be identified on GitLab with these 2 strings.
 This configuration step should be done once per computer, the first time you use git.
 ## Configure SSH keys
 The GitLab of ULiège does not allow you to use your student-ID / password for git commands. It uses a pair of "SSH keys" (one "private key" that should never be shared with anyone and a "public key" which can be given to anyone who wants to check that you own the "private key").
 On GitLab, go to the [Edit Profile](https://gitlab.uliege.be/-/profile) of your account (upper right corner of the GitLab website)
 ![](git_settings.png){width="30%"}
 Then choose "SSH keys" on the menu on the left.
 Follow the [procedure](https://gitlab.uliege.be/help/user/ssh.md#generate-an-ssh-key-pair) to create a SSH-key pair (in a "git-bash" terminal on Windows, or a terminal on the other platforms).
 Use the "RSA" type, which is more compatible with older machines.
 ```
 $ ssh-keygen -o -t rsa -b 4096 -C "demo"
 Generating public/private rsa key pair.
 Enter file in which to save the key (/c/Users/boman/.ssh/id_rsa):
 Enter passphrase (empty for no passphrase):
 Enter same passphrase again:
 Your identification has been saved in /c/Users/boman/.ssh/id_rsa.
 Your public key has been saved in /c/Users/boman/.ssh/id_rsa.pub.
 The key fingerprint is:
 SHA256:8ijxJLH1SETJZVkbRbBUXXdlmXE17C3mspK/KrSC/Jc demo
 ```
 You can use an empty passphrase if you do not share your private key (if it stays on your laptop, or if you trust the system administrator).
 The previous command created 2 files located in `c:\\Users\\your_name\\.ssh\\` (Windows) or `\~/.ssh/` (anywhere else): a public key `id_rsa.pub` and a private key `id_rsa`. The private key is similar to a password. Anyone who owns this file is able to behave as you on GitLab! It should never be shared if it is not protected by a password!
 Open the public key (file `.ssh/id_rsa.pub`) in an editor...
 ![](git_pubkey.png)
 ...and copy/paste its contents to the box in the SSH keys of the GitLab website.
 On Linux, this can be done by displaying the public key in the terminal:
 ```
 cat ~/.ssh/id_rsa.pub
 ```
 then selecting it with the mouse and using the middle mouse button to paste it in the GitLab box.
 ![](git_addkey.png)
 Then click on the "Add" button on the GitLab page.
 You can test that you are able to connect to GitLab with the following command in a terminal (check that you target `gitlab.uliege.be` instead of `gitlab.com` in the instructions from GitLab!):
 ```
 ssh -T git@gitlab.uliege.be
 ```
 which produces the following output:
 ```
 The authenticity of host 'gitlab.uliege.be (139.165.47.38)' can't be established.
 ECDSA key fingerprint is SHA256:4DyJeec4s+THW2EOZw5xjGgk6ZUcgmWjCcX33hVep7g.
 Are you sure you want to continue connecting (yes/no)? yes
 ```
 answer `yes` (you will be asked only once per machine).
 ```
 Warning: Permanently added 'gitlab.uliege.be,139.165.47.38' (ECDSA) to the list of known hosts.
 ```
 ```
 Welcome to GitLab, @Your_name!
 ```
 If you do not get the welcome message "Welcome to GitLab\`, something went wrong in the previous steps. Read again the instructions.
 # Clone the repository
 You should now be able to retrieve the code from this repository with the following command:
 ```
 git clone git@gitlab.uliege.be:rboman/math0471.git
 ```
 # Learn git
 There are numerous tutorials on git on the web:
 - [GitLab tutorials](https://docs.gitlab.com/ee/gitlab-basics/)
 - [Official git documentation](https://git-scm.com/doc)
 - [Atlassian tutorial](https://www.atlassian.com/fr/git/tutorials)
 - ...
 There are also several e-books, which can be legally downloaded from [ULiège's library](https://lib.uliege.be) (use VPN - [search for "git"](https://explore.lib.uliege.be/discovery/search?query=any,contains,git&tab=ULIEGE&search_scope=ULIEGE&vid=32ULG_INST:ULIEGE&offset=0)) or the internet (e.g. [Pro Git](https://git-scm.com/book/fr/v2)).
 You may also have a look at this presentation [Git at ULiège by R.Boman (in French)](http://metafor.ltas.ulg.ac.be/dokuwiki/\_media/devel/git_latest.pdf).
 If you prefer youtube videos, here are some links about git and GitLab:
 * [Git for GitLab (Beginner's FULL COURSE)](https://www.youtube.com/watch?v=4lxvVj7wlZw&ab_channel=ValentinDespa)
 * [Learn GitLab in 3 Hours | GitLab Complete Tutorial For Beginners](https://www.youtube.com/watch?v=8aV5AxJrHDg&ab_channel=LambdaTest)
 # Basic git workflow
 Create a repository:
 * Do this on GitLab, 1 project per group,
 * invite your co-workers as members of the project (developers),
 * invite also the instructors.
 Clone the repository:
 ```
 git clone [copy/paste the URL here starting with git@]
 ```
 Get the current state of the working copy (each time you have a doubt!):
 ```
 git status
 ```
 Create a branch named `mybranch` (you can use your family name instead):
 ```
 git checkout -b mybranch
 ```
 Switch to the _existing_ branch `otherbranch`:
 ```
 git checkout otherbranch
 ```
 See the modifications of your _working copy_ (the files on your laptop):
 ```
 git diff
 ```
 Create a local commit on your laptop:
 ```
 git add [files]  # or "git add ." to add everything (BUT be careful!)
 git status       # always check what will be commited!
 git commit -m "type a meaningful description"
 ```
 Remove a file:
 ```
 [remove the file from your hard drive]
 git add [file]         # you must "add" the deletion!
 git commit -m "[file] removed"
 ```
 Send the commit(s) of the current branch to GitLab (case 1: the branch _does not exist_ on GitLab):
 ```
 git push -u origin mybranch
 ```
 Send the commit(s) of the current branch to GitLab (case 2: the branch _does already exist_ on GitLab):
 ```
 git push
 ```
 Copy the state of GitLab to your `.git` folder (this does not modify your files - do this as soon as you know that new commits have been sent to GitLab by the other developers):
 ```
 git fetch
 ```
 Merge `otherbranch` into `mybranch`:
 ```
 git checkout mybranch         # be sure to be on your branch!
 git fetch                     # retrieve the last state of all branches
 git merge origin/otherbranch  # do the merge
 # [ resolve conficts with an editor]
 git add [files where conflicts occured]
 git push
 ```
 Retrieve the commits of the current branch that are on GitLab but are not on my PC (this is useful if you switch to someone else's branch or if you work from 2 different places such as your laptop and the CECI clusters):
 ```
 git pull
 ```
 See the "tree of commits" graphically on your Windows PC:
 ```
 gitk --all
 ```
 Create a "merge request" (instead of pushing to the main branch named `main` - it is called `master` in older repository):
 * Do this on GitLab.
 * First, merge `main` into your branch.
 * Check that your code works correctly and that you have not broken something (run the tests and check the results!)
 * Write some text explaining what you have done in your branch.
 * The other developers will receive an e-mail telling them that you want to update `main`.
 * Wait for their comments and agreement before merging the merge request.
 Tag your project for a deadline (a "tag" is a string which identifies a particular commit of your project):
 * Do this on GitLab.
 # Hints
 * Do not push unnecessary files! Add a `.gitignore` to your project. Always check that you do not send the numerical results of your code or the program binaries (executables) to GitLab. This is very important because it is not easy to remove files from the history stored on GitLab.
 * Keep the `main` branch stable (it should always produce no errors during the build and all the tests should run successfully!).
 * Tell what you are currently doing to the other developers (using comments, issues, merge requests on GitLab... or by any other mean such as messenger, e-mails or, even better, face-to-face).
 * Most of the previous commands are integrated into [VS Code](Visual%20Studio%20Code). You can easily see the modified files, prepare a commit or resolve conflicts (through the GUI, with your mouse!).
\ No newline at end of file