mar-push.md

+---
+title: Pushing MAR code changes from a cluster or lab machine
+---
+This tutorial describes how you can commit and push MAR code changes on a GitLab repository (such as [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable)) from a cluster or lab machine (such as climato.be) using a few ``git`` commands.
+
+>**Reminders about ``git`` terminology:**  
+>-a commit is essentially a checkpoint in the history of a ``git`` repository, saving file changes along with (preferably) a short description,  
+>-a push consists of synchronizing your code changes with a remote repository, such as a copy on GitLab.
+>
+>As such, there can be multiple commits before a push operation, and commits can be done exclusively on your local copy of a repository before pushing them.
+
+## Prerequisites
+
+First of all, you should have a copy of any MAR repository synchronized with ULiège GitLab in your work environment. In particular, you are **strongly advised** to review [this tutorial](mar-pull) first, which explains how you can synchronize your own `~/MAR` folder on a cluster or lab machine with a MAR GitLab repository such that you will pull only the source code of MAR, using _sparse checkout_. Thanks to this feature, you will be able to contribute to MAR repositories without accidentally pushing your custom files, e.g. from `~/MAR/bin` or `~/MAR/usr`.
+
+Then, pushing new code changes on a MAR repository will only be possible if the following conditions are met:
+1) you have a GitLab account, 
+2) you are a member of the [ESPECES/MAR group](https://gitlab.uliege.be/especes/mar) (contact Jean-Francois.Grailet@uliege.be to become one) and have at least _maintainer_ status (or higher, e.g. _owner_).
+
+**For ULiège users**, you can create a GitLab ULiège account by just logging in for the first time on https://gitlab.uliege.be.
+
+## Procedure
+
+The first time you will contribute to a [ESPECES/MAR](https://gitlab.uliege.be/especes/mar) repository, such as [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable), you will have to follow the next three steps: 
+1. create an access token on GitLab, 
+2. add your GitLab credentials in your work environment, 
+3. run a sequence of three ``git`` commands to add your changes to the remote repository.
+
+The first two steps above only need to be done once. Only the third and final step needs to be repeated with each contribution.
+
+### Step 1: create an access token on GitLab (only once)
+
+1. Log in to https://gitlab.uliege.be.
+2. Click on your profile icon (round with a coloured pattern) in the left-hand column, at the top right, to bring up a menu. Go to **Preferences**.
+3. In the new _User settings_ menu on the left, click on **Access tokens**.
+4. At the top right of the table (empty at first), click on **Add new token**.
+5. Give it a name and description (optional), then tick at least the ``read_repository`` and ``write_repository`` boxes. Once done, click on **Create personal access token**.
+6. On the new page, in the green box, click on the eye icon (or better still, the copy/paste icon next to it). Copy the sequence into a text file in a secure location (e.g. on your personal computer). This will be used as the starting point for the next step.
+
+### Step 2: add your GitLab credentials to your lab machine or cluster (only once)
+
+1. From any location on your lab machine (e.g., climato.be) or cluster, run the following commands to add your GitLab username and associated email address. The keyword ``--global`` ensures that this information can be used for all repositories.
+```
+git config --global user.name ‘JefGrailet’
+git config --global user.email ‘Jean-Francois.Grailet@uliege.be’
+```
+2. Run the following command, which tells ``git`` that your GitLab credentials will be stored in a document `~/.uliege-gitlab-credentials` for any repository (via ``--global``). If in doubt, you can use ``cat ~/.gitconfig`` to check that the file is listed under a _credential_ section.
+```
+git config --global credential.helper “store --file ~/.uliege-gitlab-credentials”
+```
+3. Using ``vim`` or ``gedit``,  create the document `~/.uliege-gitlab-credentials` and write the following sequence, replacing `[login]` with your GitLab username and `[token]` with the token created in the [previous section](mar-push). Save and exit the editor.
+```
+https://[login]:[token]@gitlab.uliege.be
+```
+4. Protect the `~/.uliege-gitlab-credentials` document from other users by editing the permissions with the `chmod` command, as follows. This is especially important if your home directory is accessible to others.
+```
+chmod 0600 ~/.uliege-gitlab-credentials
+```
+
+### Step 3: push your changes (in three commands)
+
+All of the following commands are to be executed from the `~/MAR` folder, assuming that you have followed all steps from the previous sections. For this tutorial, we will assume you want to modify MAR source code and push them to [ESPECES/MAR/stable](https://gitlab.uliege.be/especes/mar/stable).
+
+1. Use the ``git add path/to/changes`` command to add the files that have been modified for the next _commit_. There is no need to do this file by file or to restrict yourself to modified files: you can specify a folder path or a pattern, for example to the modified MAR source code (even if you have only changed a single file), as shown below.
+```
+git add src/forMAR/forMAR/*
+```
+2. Record a commit with a message describing the change, as shown below. As a check before the push (next step), the terminal will display all the changed files with the number of changes made. Check that everything has been correctly recorded in the list of changes.
+```
+git commit -m ‘Added Black Sea params to marmagic_mod.f90’
+```
+3. Do the push, which will actually upload the changes to the GitLab repository.
+```
+git push origin main
+```
+
+**Technical notes on the push operation:**
+* The command syntax is ``git push [remote] [branch name]``, ``[remote]`` being the label to denote the GitLab repository you are synchronized with.
+* If you followed the tutorial "[Getting the latest version of MAR (code only)](https://gitlab.uliege.be/groups/especes/mar/-/wikis/mar-pull)", ``[remote]`` should be replaced by ``origin``, while the ``[branch name]`` to which you will push the changes is ``main``.
+  * Keep in mind these are just labels: ``[remote]`` could be any label, as long as you use it consistently in your ``git`` commands.
+* Be doubly sure that the branch name is consistent with the remote repository. If the branch name you push on is not an existing branch, you may accidentally create a new branch.
+  * If this happens, do not worry too much: branches can be easily deleted, including from the Web interface of GitLab.
+
+## Notes and tips
+
+* If you enabled _sparse checkout_ (notably with [the previous tutorial](mar-pull)), you don't need to do anything extra to push code changes. _Sparse checkout_ works both ways: you can pull from and push on a remote repository while working only on a subset of files.
+* You can use the ``git log`` command to review the history of commits, including those that have not been pushed yet. Use the arrows to browse it, and type ``q`` to quit.
+  * ``git log`` alone will print a detailed history.
+  * ``git log --oneline`` prints a summarized history, with one line per commit.
+  * ``git log -X`` prints only the X last commits. E.g., ``git log -10`` will give the last 10 commits. It can also work in conjunction with ``--oneline``, e.g., ``git log -10 --oneline`` will print the last 10 commits with one line per commit.
+* Alternatively, ``git show`` will print a detailed description, complete with all changes, of the latest commit.
\ No newline at end of file