Newer
Older
# 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
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
- 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.
You have to explicitly tell `git` which files you want to track.
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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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.