Skip to content

Changes

Page history
Update Pushing MAR code changes authored by Grailet Jean-François's avatar Grailet Jean-François
Show whitespace changes
Inline Side-by-side
mar-push.md
View page @ ee53e0c6
---
title: Pushing MAR code changes
---
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:**
......@@ -12,7 +11,7 @@ This tutorial describes how you can commit and push MAR code changes on a GitLab
## 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`.
First of all, you should have a copy of any MAR repository from 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 pull a (sparse) copy of one of our repositories on a cluster or lab machine and link it with your own `~/MAR` folder. Doing so, you will also 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,
......@@ -20,47 +19,52 @@ Then, pushing new code changes on a MAR repository will only be possible if the
**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 set up your authentication method before actually contributing. Hopefully, setting up your authentication method needs to be done only once. After that, you can run a minimum of three ``git`` commands to bring changes to the remote repository.
## Authenticating with GitLab (only once)
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.
There are two main methods of authentication: through SSH ([Secure Shell](https://en.wikipedia.org/wiki/Secure_Shell)) or through HTTP(S) via a Personal Access Token (PAT). The former can be set up for an indefinite amount of time (i.e., SSH keys do not have to be renewed), while the latter must be renewed at least once year, though it's also more straightforward to set up.
The first two steps above only need to be done once. Only the third and final step needs to be repeated with each contribution.
### Authentication method n°1: SSH keys
### Step 1: create an access token on GitLab (only once)
### Authentication method n°2: Personal Access Token (PAT)
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)
5) Give it a name and description (optional), then tick at least the ``read_repository`` and ``write_repository`` boxes. To make your token valid for one year, click on the white cross on a black background in the _Expiration date_ field (by default, the token will be valid for a month). 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 your clipboard or a text file in a secure but temporary location (e.g. on your personal computer).
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.
7) Now, 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.
8) 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 a text editor such as ``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#step-1-create-an-access-token-on-gitlab-only-once). Save and exit the editor.
9) Using a text editor such as ``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 at step 6 (if you copied it to a temporary file, now is a good time to delete it). 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.
10) Finally, protect your `~/.uliege-gitlab-credentials` file 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)
## Pushing 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).
All of the following commands are to be executed from the directory where you copied a ESPECES/MAR repository (if you followed [the previous tutorial](mar-pull), such folder may be `~/GitLab/MAR/stable`), 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`` will then detect the modified files by itself.
```
......@@ -82,9 +86,39 @@ git push origin main
* 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
## Troubleshooting a failed push
In some cases, the ``git push origin main`` operation may abort. Hopefully, in most cases, a few extra ``git`` commands can be used to fix the issue.
### Problem n°1: your local copy is several commits behind
A push may fail simply because you are one or several commits behind the remote repository. In other words, the remote repository has been updated at least once since the last time you pulled content from it. Hopefully, with the next ``git`` commands, you can catch up with the remote repository while saving your local changes to eventually push them.
1) First, you need to cancel the commit(s) you wanted to push, but in a way that keeps the files you have modified. For this purpose, we will use ``git reset`` with the ``--soft`` option. This **``--soft`` is very important**, as it will keep the changes you've made locally. You can complete this command with ``HEAD~1`` to tell ``git`` to undo the latest commit only. If you planned to make multiple commits in one push, repeat the operation until all your planned commits are cancelled, using ``git log`` to control the state of the commit history.
```
git reset --soft HEAD~1
```
2) Now, use the ``stash`` command of ``git``. This command will put aside all changes you've made since the latest commit, which is currently the latest commit you pulled from the repository (see Step 1).
```
git stash
```
3) Catch up with the remote repository using the next two commands, assuming your remote repository is labelled `origin` and the branch you want to push on is `main`.
```
git rebase origin/main
git pull origin main
```
4) Restore your changes with ``stash pop``. From this point, you can follow the same three steps as usual to commit and push code changes.
```
git stash pop
```
**Important remark:** if the new commits pulled at step 3 brought changes to files you have modified yourself, you may want to review or event back-up them before using ``git stash pop``, otherwise you may overwrite another colleague's work !
## Miscellaneous 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.
......
......