Changes

Page history
Update Getting the latest version of MAR (code only) authored by Grailet Jean-François's avatar Grailet Jean-François
Show whitespace changes
Inline Side-by-side
mar-pull.md
View page @ 6057fa1a
---
title: Getting the latest version of MAR (code only)
---
If you're already a MAR user, there's a good chance you already have set up a `~/MAR` folder somewhere on a cluster or laboratory machine (e.g., climato\.be for ULiège researchers), where you would find (some of) the content stored in a MAR repository such as [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable).
However, for various reasons, there's also a good chance you have already tuned some files present on this repository for your own needs, typically in `~/MAR/bin` and `~/MAR/usr`. Therefore, if you cloned or pulled the entire [ESPECES/MAR/stable repository](https://gitlab.uliege.be/especes/mar/stable) in your ``~/MAR`` folder, you may overwrite some of your own scripts in the process.
In this tutorial, you will learn how you can get only a subset of files and/or folders from a ``git`` repository. This boils down to running a few ``git`` commands to set up a _sparse checkout_ of a repository.
In this tutorial, we will review a way to always get the latest source code of MAR (and NESTOR) from our GitLab which guarantees the customized files stored in your `~/MAR` do not conflict with the remote repository.
## Prerequisites
First of all, make sure ``git`` is available on the computer where you want to synchronize your ``~/MAR`` folder with a repository from this GitLab group. You do not necessarily need the latest version, but make sure to have at the very least [version 2.25](https://github.blog/open-source/git/highlights-from-git-2-25/), which comes with ``git sparse-checkout``, a useful command which will simplify updating your _sparse checkout_.
First of all, make sure ``git`` is available on the computer where you want to synchronize your ``~/MAR`` folder with a repository from this GitLab group. You do not necessarily need the latest version, but make sure to have at the very least [version 2.25](https://github.blog/open-source/git/highlights-from-git-2-25/), which comes with ``git sparse-checkout``, a useful command which will simplify the management of a _sparse_ copy of a repository (i.e., copying only specific elements).
Second, on the same computer, run this command:
......@@ -31,36 +30,50 @@ Note that you can easily check your global ``git`` parameters by viewing the con
For this example, we will assume you want to get the `src/forMAR/forMAR` folder from the [ESPECES/MAR/stable repository](https://gitlab.uliege.be/especes/mar/stable). In other words, you want to get the latest stable version of MAR.
1) For a smooth process, make sure first that there is no existing `src/forMAR/forMAR` folder or symbolic link in your `~/MAR` folder. In the former case, change the name of the folder (e.g., `src/forMAR/forMAR-old`) if you want to keep a copy of it, and in the latter case, delete the symbolic link.
1) Make sure first that there is no existing `src/forMAR/forMAR` folder or symbolic link in your `~/MAR` folder. In the former case, change the name of the folder (e.g., `src/forMAR/forMAR-old`) if you want to keep a copy of it, and in the latter case, delete the symbolic link.
2) Still in your `~/MAR` folder, initialize ``git``.
2) At a suitable location of your choice, create a directory where you will store the contents of the repository. For this tutorial, we will create `~/GitLab/MAR/stable`, where `GitLab/MAR` refers to the GitLab group and `stable` to the repository itself. In practice, you can name the folder as you wish. Once created, go into this new directory.
```
mkdir -p ~/GitLab/MAR/stable
cd ~/GitLab/MAR/stable
```
3) In the newly created directory, initialize ``git``.
```
git init
```
3) Add the [ESPECES/MAR/stable repository](https://gitlab.uliege.be/especes/mar/stable) as a remote source named ``origin``, as follows.
4) Add the [ESPECES/MAR/stable repository](https://gitlab.uliege.be/especes/mar/stable) as a remote source named ``origin``.
```
git remote add origin https://gitlab.uliege.be/especes/mar/stable.git
```
4) Enable _sparse checkout_.
5) Enable _sparse checkout_.
```
git config core.sparseCheckout true
```
5) Add the path you want to get from the target repository, in this case ``src/forMAR/forMAR/*`` from [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable), to the `git` configuration stored in `~/MAR/.git`.
6) Add the path you want to get from the target repository, in this case ``src/forMAR/forMAR`` from [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable), to the `git` configuration stored in `~/MAR/.git`. Add a slash (``/``) before the path to specify you want ``src/forMAR/forMAR`` from the root of the repository.
```
echo "src/forMAR/forMAR/*" >> .git/info/sparse-checkout
echo "/src/forMAR/forMAR" >> .git/info/sparse-checkout
```
6) Get the latest version of the source code of MAR with a pull.
7) Get the latest version of the source code of MAR with a pull.
```
git pull origin main
```
8) Go back to your `~/MAR` folder and create a symbolic link towards the directory where you stored contents from the GitLab repository. In this specific scenario, this amounts to go into `~/MAR/src/forMAR` and create a symbolic link to `~/GitLab/MAR/stable/src/forMAR/forMAR`.
```
cd ~/MAR/src/forMAR
ln -s ~/GitLab/MAR/stable/src/forMAR/forMAR
```
You `~/MAR` folder is now linked to a _sparse_ copy from the [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable) repository, guaranteeing you can always work with the most up-to-date source code of MAR.
## Updating your repository again
If you followed all previous steps correctly, the next time you want to update, you will only need to run the final command from the previous section (while in `~/MAR`).
If you followed all previous steps correctly, the next time you want to update, you will only need to go inside the directory synced with the repository (thus, `~/GitLab/MAR/stable` in this context) and run the final command from the previous section (while in `~/MAR`).
```
git pull origin main
......@@ -68,11 +81,11 @@ git pull origin main
## Restoring repository code (undo local changes)
Let us assume you pulled the contents of `src/forMAR/forMAR` from [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable) in your `~/MAR` folder, as suggested earlier, and modified a few files in your own `~/MAR/src/forMAR/forMAR` folder to prepare a MAR executable.
Let us assume you pulled the contents of `src/forMAR/forMAR` from [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable), as suggested earlier, and modified a few files in your own `~/MAR/src/forMAR/forMAR` (which is actually a symbolic link to `~/GitLab/MAR/stable/src/forMAR/forMAR) to prepare a MAR executable.
For example, you modified `src/forMAR/forMAR/mar_ecrad_mod.f90` to tune parameters of the radiative transfer scheme ecRad, or changed `src/forMAR/forMAR/mar_ib_mod.f90` to tune the outputs (e.g., to produce hourly outputs instead of daily outputs).
For example, you modified `~/MAR/src/forMAR/forMAR/mar_ecrad_mod.f90` to tune parameters of the radiative transfer scheme ecRad, or changed `~/MAR/src/forMAR/forMAR/mar_ib_mod.f90` to tune the outputs (e.g., to produce hourly outputs instead of daily outputs).
However, you now want to revert these local changes, either to tune a new MAR executable or to update your copy without having conflicts. You can then use the next ``git`` command.
However, you now want to revert these local changes, either to tune a new MAR executable or to update your copy without having conflicts. You can then use the next ``git`` command from your copy of the repository.
```
git restore src/forMAR/forMAR
......@@ -82,13 +95,13 @@ The syntax is ``git restore [path]`` where ``[path]`` (a mandatory argument) can
## Adding other paths to the _sparse checkout_
If you want to expand your _sparse checkout_ to get other parts of a repository, you can edit `.git/info/sparse-checkout` (e.g., with ``vim`` or ``gedit``) in the folder where you initialized ``git`` (`~/MAR`, in this case) and add more paths or patterns. The `.git/info/sparse-checkout` file itself is interpreted by ``git`` more or less in the same way as a ``.gitignore`` file.
If you want to expand your _sparse_ copy to get other parts of a repository, you can edit `.git/info/sparse-checkout` (e.g., with ``vim`` or ``gedit``) in the folder where you initialized ``git`` (`~/GitLab/MAR/stable`, in this case) and add more paths.
For example, if you want to also extract the latest version of NESTOR from [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable), you can edit `.git/info/sparse-checkout` in `~/MAR` to have the following content.
For example, if you want to also extract the latest version of NESTOR from [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable), you can edit `.git/info/sparse-checkout` in `~/GitLab/MAR/stable` to have the following content.
```
src/forMAR/forMAR/*
src/NESTOR/NESTOR/*
/src/forMAR/forMAR
/src/NESTOR/NESTOR
```
After saving changes, tell ``git`` to update itself with respects to the new _sparse checkout_ configuration with the following command (again, to run in `~/MAR`).
......@@ -99,6 +112,8 @@ git sparse-checkout reapply
## Removing paths from the _sparse checkout_
If you want to remove paths from the _sparse checkout_, you can follow the same approach as in previous section and simply remove paths you no longer need from `.git/info/sparse-checkout`, but **consider backing up the files from the removed paths**. Indeed, ``git sparse-checkout reapply`` will remove the files associated to the removed paths from your local copy.
If you want to remove paths from the _sparse checkout_, you can follow the same approach as in previous section and simply remove paths you no longer need from `.git/info/sparse-checkout`.
However, **please note this will remove the files associated to the removed paths from your local copy**. Hopefully, you can easily restore the removed files by simply modifying again `.git/info/sparse-checkout` to add the previously removed paths and running ``git sparse-checkout reapply`` again. You can then make a back-up of the files (if needed) before removing the paths again.
_Parts of this tutorial have been translated from French notes with [DeepL](https://www.deepl.com) and proofread._
\ No newline at end of file