Skip to content
Snippets Groups Projects
Readme.md 6.18 KiB
Newer Older
Facundo Muñoz's avatar
Facundo Muñoz committed
# 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.

Facundo Muñoz's avatar
Facundo Muñoz committed
## __Mission 1__ Get started with `git` locally

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


1. Install `git` on your computer
Facundo Muñoz's avatar
Facundo Muñoz committed

`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


Facundo Muñoz's avatar
Facundo Muñoz committed
2. Install a `git` _client_ (optional)
Facundo Muñoz's avatar
Facundo Muñoz committed

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


Facundo Muñoz's avatar
Facundo Muñoz committed
3. Set up a working directory for the tutorial
Facundo Muñoz's avatar
Facundo Muñoz committed

- 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.


Facundo Muñoz's avatar
Facundo Muñoz committed
4. Set up a `git` local repository in your working directory
Facundo Muñoz's avatar
Facundo Muñoz committed

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. 

Facundo Muñoz's avatar
Facundo Muñoz committed
5. Commit the first version of your work
Facundo Muñoz's avatar
Facundo Muñoz committed

You have to explicitly tell `git` which files you want to track.
Facundo Muñoz's avatar
Facundo Muñoz committed
For the moment, we will track everything: `git add .`
Facundo Muñoz's avatar
Facundo Muñoz committed
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.

Facundo Muñoz's avatar
Facundo Muñoz committed
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

Facundo Muñoz's avatar
Facundo Muñoz committed
__Objective:__ You will be able to share your work with colleagues.


Facundo Muñoz's avatar
Facundo Muñoz committed
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.

Facundo Muñoz's avatar
Facundo Muñoz committed
Go ahead and explore a bit. Configure your settings and set up your profile.

Facundo Muñoz's avatar
Facundo Muñoz committed

2. Establish secure communication between `git` and Forgemia.

Facundo Muñoz's avatar
Facundo Muñoz committed
This is very OS-dependent. But here are detailed instructions for every platform.

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

Also here:

Facundo Muñoz's avatar
Facundo Muñoz committed
https://docs.gitlab.com/ee/gitlab-basics/create-your-ssh-keys.html#create-and-add-your-ssh-key-pair
Facundo Muñoz's avatar
Facundo Muñoz committed

Facundo Muñoz's avatar
Facundo Muñoz committed
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.
Facundo Muñoz's avatar
Facundo Muñoz committed

Facundo Muñoz's avatar
Facundo Muñoz committed
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.