Git: How to - CompEngIoT-UnicalStudentsOrg/SB-Documentation Wiki

This project is managed through the git versioning software. Git allows you to work on a project in a distributed way, where you can contribute at the same time as other people in a team.

Table of contents

Installing git

Windows

https://git-scm.com/download/win

Linux

https://git-scm.com/download/linux

Getting a copy of the project

Once you install git, you can start working on the project. To do so, you have to get a copy of the project where you can work on. I suggest you to work with an editor like vscode, you can get it here.

Once you install vscode, you can get the project and work on it by opening a command line shell and executing the following commands:

git clone https://github.com/CompEngIoT-UnicalStudentsOrg/SB-Documentation
cd SB-Documentation
code .

Working on a task

When we decide on which task to execute, we create an issue in github describing the task. To add new material to the git repository we need to commit our work on the right branch.

A branch is used to work on a feature tied to a task in isolation, without notifying everyone each time you make something new. You work on a feature branch and, when you finish your task. You open a pull request specifying the task you worked on. Someone else will then review your changes and merge them into the main/master branch. The main/master branch is the branch containing the most up to date and stable version of the project.

When you start to work on a branch, you have to create a branch with the same name of the issue. If for example the issue you're working on is called Implementing feature X, then the branch will be called implementing-feature-x.

Before creating a branch you want to have the last version of the main branch. To do so and then create your feature branch, do the following:

cd SB-Documentation
git checkout main
git fetch
git pull
git checkout -b new-branch-name
git push origin new-branch-name

In order, these commands will change directory into the one of this project, switches to the main branch, fetches the new data from github, pulls them into your local copy, creates a new branch called new-branch-name starting from the main branch, and then creates that branch on github too.

Once you do that you are ready to work on your task.

Committing changes

After you work for a bit on your task, you can commit any changes that you want using the git commit command. If you use vscode, you can do that directly from View -> SCM. Once you click on that menu, a view on the left opens up.

In this view you can click on the + symbol on each file you want to commit, then write a commit message with the right format specified in the commit strategy wiki page in the Message area. Once you commit your changes, you can push them by clicking on the three dots near the commit message area and then click on push.

Opening a pull request

After you commit changes for a couple of times, if you think you have finished your task, you can request to merge your work into the main branch by opening a pull request. You can open one by going to pull request -> new pull request, and choosing the main branch as the base, and your branch as the compare one. Assign the pull request to yourself and assign the review process to someone else. When the reviewer checks it, they will decide if it's ok to merge and do so.