Tutorial Forgemia

This tutorial is structured as a series of missions or challenges. Each one should be easy to accomplish. You will progressively unlock the skills needed to use git at a basic level for collaborating on Forgemia.

I will provide links to necessary materials and to further information.

Mission 1 Get started with git locally

Objective: You will be able to version-control your own work.

1. Install git on your computer

git is a program for managing versions of code (or text). Install it and set it up.

https://happygitwithr.com/install-git.html https://happygitwithr.com/hello-git.html

2. Install a git client (optional)

This is a program that interfaces git and provides a graphpical user interface, similar to RStudio interfacing R. There are plenty of options both commercial and free, depending on the operating system.

I will use barebones git in the tutorial to cover the basics. But you are welcome to try some client.

https://happygitwithr.com/git-client.html

3. Set up a working directory for the tutorial

• Create a new directory called Forgemia_test.
• Create a plain text file named script.R with a few lines of code within a subdirectory src.
• Create a plain text file named Readme.md and write a title and some description of this test project.
• Create a Word document named binary.docx and write a few words.

4. Set up a git local repository in your working directory

Open a terminal and change to your working directory. Run git init in order to set up a git local repository and start tracking versions. Running git status will inform you that your files are untracked.

5. Commit the first version of your work

You have to explicitly tell git which files you want to track. For the moment, we will track everything: git add . We will create the first version (think of a snapshot of your work at this time) with git commit -m "Initial commit".

What commes after -m is a label known as commit message that informs about the purpose of the changes.

Running git status now should say that nothing has changed in your working directory since the last version.

6. Make and explore changes

Go make some changes in both the script.R and binary.docx. Try git diff. Git will tell you which files have changed since last version, and what the changes were... as far as it can read (i.e. not in binary.docx)

Deliverable: The output of git diff

Summary: You have set up git in your local computer and learnt how to set up new repositories with git init, track new files with git add, make new versions with git commit, check the state of the repository with git status and see the latest changes with git diff.

You are now ready to version-control your own work in your computer.

Congratulations!! you have completed your first mission towards learning how to collaborate with git and Forgemia. Send me the deliverable by e-mail and you will be able to continue with your second mission.

Mission 2 Get started with Forgemia

Objective: You will be able to share your work with colleagues.

1. Ceate an account on Forgemia using your credentials from Cirad.

Go to https://forgemia.inra.fr/ and click on "Connexion SSO". Select Cirad on the list of institutions and log in with your credentials.

That's it! the first time you do this, Forgemia creates your account.

Go ahead and explore a bit. Configure your settings and set up your profile.

2. Establish secure communication between git and Forgemia.

This is very OS-dependent. But here are detailed instructions for every platform.

https://forgemia.inra.fr/help/ssh/README.md

Also here:

https://docs.gitlab.com/ee/gitlab-basics/create-your-ssh-keys.html#create-and-add-your-ssh-key-pair

Let me know which one worked best for you.

These two steps are only required once for each computer you use.

3. Set up a new project in Forgemia as a remote repository of your local one

Search for "New project" in the top bar (symbol "+"). Name it "Forgemia test", give it a description. Establish the visibility as "Internal". Leave everything else as is.

In particular do not initialize it with a README file. This is for a case where you start your project here. We already have a local repository.

4. Link your local and remote repositories

Go back to your command line and type the following:

git remote add origin git@forgemia.inra.fr:umr-astre/forgemia-tutorial.git
git push -u origin --all

This adds a remote repository named origin at the given URL (there can be multiple remotes). The second line "pushes" all your local history to the remote repository creating permanent links between the corresponding branches. So far, you have a single branch, named "master". But you could create more, where you can develop things in parallel without breaking anything in the master branch.

If refresh your web browser, you should see your files and the contents of your Readme.md file rendered as a welcome page.

This is only needed the first time you create your project.

5. Push new changes to the remote repository

If you look closely, your files in Forgemia are not identical to those in your working directory. The last local changes have not been yet commited. They exist only in your Working space

git status tells you which files have changed.

git add . marks all your changes for commit. You could want to commit only part of the changes, or changes to some of the files only.

git commit -m "Changed the script and the doc" will create a new version in the local repository

git push will send the updates to Forgemia.

Deliverable: The URL of your Forgemia repository.

Summary: You have set up your Forgemia account and created a remote repository linked to your local git repository. These are operations needed only at the start of a project. You commited new changes to the local repository and then pushed them to the remote repository.

You are now ready to share your version-controled work with your colleagues.

Congratulations!! you have completed your second mission towards learning how to collaborate with git and Forgemia. Send me the deliverable by e-mail and you will be able to continue with your third mission.