Gitlab is used as a reference repository and as a versionning and developping tool for MAR.
Join the MAR project on Gitlab:
- Go to the GitLab page. If you do not have an account yet on this website, select “Singn Up” and fill the form, you will then receive an email to activate your account.
- Go back to the GitLab page, and complete your registration by setting a login and filling the requested information.
- Join the MAR Project on Gitlab. To do so, go to the "Browse Projects" section, select “All” in the upper left panel and search for Mar-Group. Select the model version you want to download (e.g. MARv3). Once found, select "Request to join". You will be granted access as user (read-only permission on the git repository) or developer (read/push permission on the git repository) as soon as an administrator validates your request. An email will be sent to notify the acceptance.
- Later on, you can connect at any time and update your profile through GitLab by selecting “Sign In” , and go to the Mar-Group project.
Access the MAR git repository through your public key:
It is recommended to upload your public key on gitlab to facilitate the use of git commands. First of all, make sure you have an access to the appropriate MAR version on Gitlab (see above). A complete documentation on this procedure can be found here, but a short version is summarized here.
- First, generate a key pair on your machine through the following commandline:
- ssh-keygen -t rsa -b 4096
- It is recommended to keep the default options. A password will be asked to encrypt the private key, either use a passphrase or hit the enter/return key to have an access with no password.
- Then paste it on GitLab in the "Setting" > "SSH Key" section. Indicate a title to remember to which machine it corresponds as you can upload public keys from several machines. Don't forget to select "Add Keys" once you're done.
Below are presented several options to use MAR. The first one (Clone) is for simple users who do not plan to substantially modify the code or create new routines; the second one (Fork) is for users who plan to substantially modify the code and who may at some point request the MAR developers to include their developments in the main repository; the last one (Manage) is reserved to the core developers who will create new versions or for shared developments within a version.
Clone (download) the MAR repository [users only]:
- If you just want to download MAR and follow the updates, you can find the URL on the Gitlab page corresponding to the version you wish to download (above the list of directories). Select "SSH" and click on "Copy URL to clipboard", and use the "git clone" commandline to clone it, for example:
- git clone firstname.lastname@example.org:Mar-Group/MARv3.7.git
- Note that if you prefer not to use your public key, select the "HTTPS" option rather than "SSH", and use the "git clone" commandline with that URL.
- At any time, you can check updates by doing:
- At any time, you can pull the updates by doing:
- You can also look for a specific version of MAR. Lo list all available versions, do:
- And to download a specific version, first run the aforementioned 'git clone' command if not already done, then use git checkout, for example:
Fork the MAR repository [occasional developers]:
This section is reserved to users who plan to significantly modify the code but are not part of the MAR core developers. This is typically the way to go for a PhD planning some hard work on the MAR code. Forking the MAR repository is equivalent to duplicating the original MAR Gitlab repository as one of your own Gitlab projects. This means that you can use all the git commands to save and tag your modifications (see next section) into your own project repository.
- To fork the original MAR repository, go to the MAR page on Gitlab (https://gitlab.com/Mar-Group/MARv3.7) and click on the "Fork" button.
- Then, clone it on your machine, e.g.:
- git clone email@example.com:bobby/MARv3.7.1.git MY_MAR
- You can tell git to take a new file into account by doing:
- git add <file> # or -A for all files
- Then, to upload your modifications into your Gitlab project:
- commit -m 'your text' <file> # or --all for all files
- git push
- If at some point you want to share your modifications with the core developers (i.e. for integration into the reference repository), go to Gitlab (e.g. https://gitlab.com/bobby/MARv3.7.1) and click on "Merge Request".
- If at some point you need to update your forked repository with the original repository:
- cd MY_MAR # forked repo
- git remote add upstream firstname.lastname@example.org:Mar-Group/MARv3.7.git # original MAR repo
- git fetch upstream
- git pull upstream master # adapt 'master' if you want to fetch from another branch
- git push
Manage MAR developments [core developers only]:
To be able to contribute to the MAR repository, you need to be granted a “developer” status (check your status in the MAR project on "Setting” in Gitlab). To change your status, ask to email@example.com
- Modify and create files in your cloned MAR directory. Once you have tested your modifications, you can tell git to take the new files into account by doing:
- To tell git to take the modifications of existing files into account, do:
- git commit –m “your message” --all
- Then, to push your new and/or modified files onto the MAR gitlab repository, do:
- To tag a model version, do:
- git tag -a v3.8.1 -m 'version 3.8.1'
- git push --tags
- If you forgot to tag an earlier version (e.g. v3.7), you can do it afterward by identifying the commit id on the Gitlab page (see 'Commits'), then, for example, do:
- git tag -a v3.7 1b9d2166be5ef48b9bc9304508e266774f712a89
- To check the status of your modifications:
For more information about git and gitlab, please consulte Git-Reference Manual and GitLab Documentation
Join the MAR mailing list:
A mailing list for the MAR community was set up to inform you about new releases, important bugs and workshops. For questions about MAR itself, please use the MAR forum instead of the mailing list.
To send an email to the MAR mailing list, use this email adress: firstname.lastname@example.org