Expand terminology and update ch 01 and 02

parent fbdc1219
# 1. Starting a new project
The basics of the **GitLab** environment.
# 1. Start a new project
This chapter contains:
- the basics of the **GitLab** environment
- the first steps of starting a new project
- the steps to convert an existing project into a Git repository
## Step 0. Logging in on GitLab
- Go to git.wur.nl
## Definitions
- **GitLab** is the online workspace that makes Git easier to use.
- Has many, many extra functions outside of Git
- Backed up at WUR, just like the W:/ drive
- Look through your project's files like a file browser
- Easily compare versions or look up an old version
- Manage contributions from the team
- Manage time planning using Milestones and Issues
- **Project** is a GitLab concept, meaning the full package of all your files,
project members, planning, issues etc.
The project exists only on [git.wur.nl](git.wur.nl), where you'll go to to use these functionalities.
The GitLab project represents
- the project folder on the W:/ drive
- and the history of all the files in that folder
- and the planning, actions and deadlines for team members
- and the framework for documenting and reporting.
- **Repository**, abbreviated to **repo**, is the part of your project that contains the files.
The repo represents **only** the project folder on the W:/ drive.
The repo is what you can download to your own computer to work on.
The repo is what the Git software interacts with.
Git does not work with the other functionalities in GitLab, just the files.
## Step 1. Log in on GitLab
- Go to [git.wur.nl](git.wur.nl)
- Log in using your WUR e-mail adress and password
- Go to git.wur.nl/overb015/git-started/
- Navigate to chapter 1 to read this document.
- Go to [git.wur.nl/overb015/git-started/](https://git.wur.nl/overb015/git-started/)
- Navigate to chapter 01 to read this document.
## Step 1. Creating the project
## Step 2. Create a new project
- In the top toolbar, click the ```+``` on the right.
- Click ```New project```
- The title should be short but complete
- The slug should be short, unique, and suitable for the project page URL
- The description should contain the WFSR project name and a purpose or objective.
- Tick the box ```Initialize repository with a README```.
- Set the visibility level to ```Public``` for now, so your project can be found by others.
- Leave the box ```Initialize repository with a README``` unchecked.
- Click ```Create project```.
## Step 3. Add files to the repository
File management on GitLab takes place in the ```Repository``` menu item
in the sidebar on the left.
- First, create a file called ```readme.md```.
**Every folder of your project should have a file with this name.**
These files are essential for proper documentation of your folders.
This is not just useful for visitors or new team members,
but also for yourself, in the future, when you're looking for a specific file.
The content of these files is displayed by GitLab when you browse a directory
that contains a readme.md file.
Use a new line for each sentence.
Try to keep the line lengths below 80 characters.
This improves the readability of raw ```.md``` files, facilitates editing,
and actually helps you structure your sentences and keep them to the point.
The ```.md``` extension refers to the markup language **Markdown**,
that you can use to format and structure your documents.
Read some basic tips on Markdown [here](https://git.wur.nl/overb015/git-started/).
- You can edit text files (including ```.md``` files such as this ```readme```)
in the browser by clicking on the file and then on the ```Edit``` button.
- You can create subfolders in the project by clicking the dropdown button ```+```
in the middle of the page near the top and selecting ```New directory```.
- You can then navigate to the new folder and create files there.
- Each of these actions is done via a **commit**.
These will be explained in
[Chapter 02](https://git.wur.nl/overb015/git-started/tree/master/02_getting_git).
# Getting Git
# 2. Get Git
In [chapter 01](https://git.wur.nl/overb015/git-started/tree/master/01_starting_a_new_project),
we made additions (changes) to the **repo**
by making a **commit** for each change.
We did that online, in the browser, using GitLab.
But committing to the repo is essentially a **Git** action;
we just used GitLab's buttons to do it the first time.
With GitLab, we can work directly on the **remote** version of the repository;
the version that is stored on the WUR infrastructure.
But in order to collaborate on a project in real time, project members
can all have a **clone** of the repo on their own computer.
## Definitions
- **Git** is software for version control of your documents and data
- Each addition and modification is tracked
- Each step is reversible; overwritten work is not lost
- Co-write a document simultaneously in two branches
- Git functionalities will be introduced step by step
- Git also works without GitLab
- Install Git for Windows [here](https://git-scm.com/downloads).
- A **commit** is a set of changes made to the repo.
Any edit to the contents of a file, or an addition, deletion, of moving of a file is one change.
You can add any number of changes to any number of files to a single commit,
but the result of the commit should affect only one, single, aspect of the project.
If you want to add file A and fix file B, make two separate commits.
If you want to make two separate changes to file B, that could be one commit.
You can view the repo as a folder that started out empty,
and was built up to the current status by a applying the list of commits in the right order.
- You give each commit a short **commit message** to describe what was changed by it.
This message should fit in 50 characters.
If you need more space to sum up your changes, write a longer message this time,
but make sure to commit smaller sets of changes next time.
- The **remote** is the central version of the repo, stored on the WUR infrastructure.
This version is the "official" state of the repo, or the consensus.
- A **clone** is a copy of the repo on your own computer.
Your repo is identical to the **remote** on GitLab at the moment you clone it,
but as you make changes to your local copy, or team members make changes to the remote,
your versions will start to have differences.
Git provides the tools we need to manage these differences.
- When you've made changes on your local copy that you want to add to the remote,
you **push** your commit to the remote.
Team members can then **pull** these changes to their local copy to stay updated.
## Step 1. Install Git
Now that the project is created, we have a **repository** to browse.
A repository is the place where your project files are.
Right now, **GitLab** @ git.wur.nl is the only place where your new project
and its ```README.md``` file are located.
You can clone this remote repository to your computer,
but for that you will need **Git**.
Follow the steps [here](https://www.stanleyulili.com/git/how-to-install-git-bash-on-windows/) to install Git.
## Step 2. Authenticate yourself
When you commit changes from your local repo to the remote,
your identity is sent along with it.
This is how everybody knows who did what in the project.
Right now, **GitLab** on [git.wur.nl](git.wur.nl) is the only place
where your new project and its files exist.
You can clone this remote repository to your computer.
We will use **Git** to do that, because it provides more tools we will need later.
Follow the steps [here](https://www.stanleyulili.com/git/how-to-install-git-bash-on-windows/)
to install Git.
## Step 2. Get to know the terminal
Run the Git Bash executable you just installed.
A **terminal** window opens where you can give commands to the computer
through the **command line**.
- Type ```pwd``` and hit ```Enter```.
You can see that the terminal shows the computer's feedback to your commands.
- The terminal is like a file browser: you are in a folder on your file system.
The folder where you are at any time is called the working directory.
The previous command, ```pwd```, short for ```print working directory```
tells you where you are.
You can use ```ls```, short for ```list``` to list the files in your working directory.
If you run a command without specifying that it should run somewhere else, it runs here.
- ```cd``` is short for ```change directory```.
Run ```cd C:/``` to go to your C:/ drive
- Run ```pwd``` again to see that you've changed location.
- Run ```ls``` to see the contents of your C:/ drive.
- We will use ```git``` commands to perform Git actions from the terminal.
## Step 3. Clone project
- Open a Git Bash terminal
- Run ```pwd``` to print your current location in the file system
- Run ```cd C:/etc/etc/``` to go to the parent folder for your project folder
- Run ```git clone https://git.wur.nl/overb015/
\ No newline at end of file
## Step 3. Clone this repository
- Run ```cd C:/path/to/your/folder/``` to go to the parent folder for your project folder
The following command will create the project folder for you.
- Run ```git clone https://git.wur.nl/overb015/``` and see what happens.
## Step 4. Authenticate yourself
In the previous step, you ran a command to download data from the Git repo at WUR,
which is a secured environment.
You need to authenticate yourself as a WUR user to access git.wur.nl from the terminal.
> TODO: add steps for authentication by trying this with a new user.
When you commit changes from your local repo to the remote,
your identity is sent along with it.
This is how everybody knows who did what in the project.
......@@ -2,14 +2,14 @@
Basic steps for Git.
## Purpose
To help teams at WFSR control their projects using Git.
To help teams at WFSR control their projects using Git.
The easy steps in this short course will teach you how to:
- start your project
- structure your project
- share your project
- successfully complete your project
## Introduction
## Definitions
- **Git** is software for version control of your documents and data
- Each addition and modification is tracked
- Each step is reversible; overwritten work is not lost
......@@ -24,27 +24,58 @@ The easy steps in this short course will teach you how to:
- Easily compare versions or look up an old version
- Manage contributions from the team
- Manage time planning using Milestones and Issues
- **Project** is a GitLab concept, meaning the full package of all your files,
project members, planning, issues etc.
The project exists only on [git.wur.nl](git.wur.nl), where you'll go to to use these functionalities.
The GitLab project represents
- the project folder on the W:/ drive
- and the history of all the files in that folder
- and the planning, actions and deadlines for team members
- and the framework for documenting and reporting.
- **Repository**, abbreviated to **repo**, is the part of your project that contains the files.
The repo represents **only** the project folder on the W:/ drive.
The repo is what you can download to your own computer to work on.
The repo is what the Git software interacts with.
Git does not work with the other functionalities in GitLab, just the files.
- A **commit** is a set of changes made to the repo.
Any edit, addition, deletion, of moving of a file is one change.
You can add any number of changes to any number of files to a single commit,
but the result of the commit should affect only one, single, aspect of the project.
If you want to add file A and fix file B, make two separate commits.
If you want to make two separate changes to file B, that could be one commit.
You can view the repo as a folder that started out empty,
and was built up to the current status by a applying the list of commits in the right order.
- You give each commit a short **commit message** to describe what was changed by it.
This message should fit in 50 characters.
If you need more space to sum up your changes, write a longer message this time,
but make sure to commit smaller sets of changes next time.
- The **remote** is the central version of the repo, stored on the WUR infrastructure.
This version is the "official" state of the repo, or the consensus.
- A **clone** is a copy of the repo on your own computer.
Your repo is identical to the **remote** on GitLab at the moment you clone it,
but as you make changes to your local copy, or team members make changes to the remote,
your versions will start to have differences.
Git provides the tools we need to manage these differences.
- When you've made changes on your local copy that you want to add to the remote,
you **push** your commit to the remote.
Team members can then **pull** these changes to their local copy to stay updated.
- **Markdown** is a simple formatting language for plain text
- File extension: ```.md```
- Used for ```readme.md``` files such as this one to provide a
- Used for ```readme.md``` files such as this one to provide a
summary of the contents of a folder
- The formatting is contained in the text, allowing the use of
line-by-line version control to manage formatting
- Supports math formulas like $`f(x) = log_{10} (y)`$
- For example, different levels of titles are formatted like this:
- Different levels of titles are formatted like this:
```
# Top level title
## Chapter title
### Section title
## Mid level title
### Low level title
Normal text.
```
Which looks like this:
# Top level title
## Chapter title
### Section title
## Mid level title
### Low level title
Normal text.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment