GIT

---

---

References:

• VS Code
• GitLab
• GitLab Extension for VS Code
• Git
• Professional Git by Brent Laster (available online in University Library)
• Git Book V2
• EBC-Tutorials
• Semantic Versioning 2.0.0
• Semantic Versioning Wikipedia

---

Introduction

Download Link

A version control system allows you to keep track of changes made to code over time. This means that you can, at any given point, revert to older versions of the code you are working on.

Git is a popular version control software that operates on a Distributed Version Control System (DVCS). This system provides every user with a copy of all files, allowing them to edit locally. Users can work on files locally and then upload them to the server. The advantage of DVCS is that if a server crashes, a local user can upload the files and restore the server since they have a complete copy of the server data.

Git stores content in the form of trees and blobs. A blob (Binary Large Object) is an object type used to store file content without metadata like the creation date of the file. A computed checksum (SHA-1) represents the file. A tree holds listings of other trees and blobs. A commit takes a snapshot of the tree at a specific moment and saves it. When you create another commit, a new snapshot is taken with only the required changes in the new commit. The old/unchanged files remain the same, and the new commit points to the old files. Thus, storage is required only for changed files.

Workflow

In Git, you have the Working Directory, Staging Area (index), .git Directory (local repository), Upstream Directory (remote repository), and Stash.

Elementary Git Workflow

1. You modify a file in your Working Directory.
2. You mark the edited files as confirmed changes and stage them. This saves only the changes as a snapshot. The original file is stored as a reference.
3. You commit those files. This takes the staged files and stores the snapshot of changes permanently in your Git repository.
4. You push your changes from the local repository to the remote repository.

Small Teams

When working in a small team, say with 2 members, your workflow will be as follows:

• Creation of a new repository either online or locally on a PC.
• Clone the repository if created online. Push the repository to the server if created offline.
• Create the required branch (e.g., feature).
• Code and test it.
• Commit the code.
• Repeat steps 4 and 5 until a certain part of the feature is ready.
• Push to the remote repository.
• Repeat steps 4 to 7 until the feature is completed.
• Merge the feature branch into the main branch.

Contributing to Online Projects

When contributing to online repositories, the following activities are typically performed:

1. Fork the project to your account.
2. Create a topic branch from the master.
3. Make some commits to improve the project.
4. Push the code to your account’s project.
5. Open a Pull Request on the platform (e.g., GitLab).
6. Discuss with the project’s team and optionally continue committing.
7. The project owner merges or closes the Pull Request.
8. Sync the updated master back to your forked project.

Commits

When you make a commit, Git stores a commit object that contains a pointer to the snapshot of the content you staged. This object also contains the author's name and email address, the message you typed, and pointers to the commit or commits that directly preceded this commit (its parent or parents): zero parents for the initial commit, one parent for a normal commit, and multiple parents for a commit that results from a merge of two or more branches.

There is no strict rule for commits, but it is suggested to have one commit per task or bug.

Commit messages are important as they provide information about what you edited in that specific commit. Thus, when you review your changes history, you can recall what you did by reading the message, or when a third person is going through your work, they can make sense of your changes if they plan to work on your repository. The suggested length of the text is 50 characters. Provide concise information in this.

For example, if you change a function in code:

• Fixing file in code // Not good
• Fix function ### // Good
• Fix function ### in file ### // Better

Git Branches

Branches are used to create a separate directory of your code and then work on that copy. This allows you to create a copy from your main working branch with all the history of changes in it. You can then work on the new branch to fix a bug or implement a new feature. Once done, you can merge the branch into your main branch.

This helps avoid editing files in a working environment. For example, you have a blink LED program that starts automatically when the board boots up. You need to implement a button trigger to start this blink. So, you create a new branch from your main branch and then implement and test your code. When everything works, you combine the changes from the new branch to the main branch.

You can also work on multiple branches simultaneously and fix a bug while working on a new feature. Just ensure that when merging your new features, you incorporate the bugs fixed on the main branch during the development of the new branch.

Merging and Merge Conflicts

To incorporate a new branch into the main branch, you use the merge command. This copies the required code from the source branch to the target branch. The source branch can then be deleted if necessary.

In a situation where two people, A and B, are working on the same project. A updates the README.md file and pushes the changes. B also adds content to README.md and tries to push the changes but gets a conflict error because B did not pull A’s updated version of README.md before pushing.

To avoid such conflicts:

• Always pull before pushing.
• Do not have more than one developer working on a specific file.
• Try merging the main branch frequently into your feature branch to keep new changes updated in your feature branch.

Tags

To mark a specific milestone for the project, tags are used. Tags are initially saved on the local repository and have to be pushed to the remote repository.

There are two types of tags:

• Lightweight: It points to a specific commit.
• Annotated: It stores the data as a full object in the Git database. It contains the tagger's name, email, and date.

The tag type depends on what information you want to save. If it's a temporary tag, a lightweight tag is a better option.

Rebase

Rebasing allows you to move commits and their history to another branch. This means you are changing the base of your branch and making it appear as if it was created from a different commit. The main use of rebasing is to have a linear commit history.

The difference between a merge and a rebase is that in a merge, if the branch moves forward with a commit, merge will create an empty commit, which will be stored in your history.

In rebase, Git finds a common commit and saves the differences after that. Then, in sequential order, it applies the changes.

• Atlassian Git Rebase Tutorial
• Atlassian Merging vs. Rebasing
• Git Book V2

Git Interface

Git is officially available as a command-line tool but is also available in different environments. You can download the Git command-line tool from here. There are various GUI tools and extensions for popular IDEs and code editors available.

Initially, you need to provide some details about yourself when you first install Git. To do so, open a new terminal or command prompt.

For Windows users, enter git config --global core.editor "notepad" in it.

Enter git config --global --edit in it. A file will open in a text editor. Enter your name and email in that file after the colon (:).

Git Commands

A basic list of commands used in Git is provided below. For additional commands, please refer to the GitHub Training.

Clone New Repository

• git clone -b <BRANCH_NAME> <REPOSITORY_URL_WITH_HTTPS>: To download the repository to your PC as a local repository.

Basic Workflow

• git status: This provides you with the current status of your repository, such as information about modified files, the last commit, and branch information.
• git add PATH_TO_FILE or git add .: It adds the files to the staging area. The dot (.) adds all changed files inside your working directory to your staging area.
• git commit -m "commit message": It moves the files from the staging area to the local repository. The -m is a required flag used to provide a sensible commit message to name the changes you made.
• git push: Publishes the changes from the local repository to the remote repository.

Make New Branch from Main

• git checkout main: To set the main branch as the default working branch.
• git pull: To download changes from the main branch.
• git branch NEW_BRANCH: Create a new branch.
• git checkout NEW_BRANCH: Select NEW_BRANCH as the default working branch.
• git push --set-upstream origin NEW_BRANCH: To set NEW_BRANCH as the default when uploading to the remote repository.

Tags

• git tag: List current tags.
• git tag -a [Name_for_Tag] [Commit_Hash_ID]: Add a tag with a specific name for a specific commit.
• git push --tags: To push tags to the remote repository.
• git push --follow-tags: Push only annotated tags to the remote repository.
• git show [TAG_Name]: Display details of a tag.
• git tag -d [Name_for_Tag]: To delete a specific tag. To remove it from the remote repository, use git push origin :[Name_for_Tag].

Amend

• git commit --amend: Adds the files to your last commit.

Log

• git log: To see the complete history of Git commits.
• q / z: To exit the log.

---

Tasks

The tasks below are designed to teach Version Control with VS Code and GitLab.

Hint: You can follow these tasks directly with Git commands in CMD/Terminal.

Task 1

Follow the steps below:

1. Open the GitLab website and log in. You will see a page with all the projects in your account.
2. Click on the New project button to create a new project. On the next page, click on Create blank project.
3. On the next page, enter the name of your project.
4. In the project URL, select your FH-Kennung number (FH identifier) (e.g., AB1234S). In the Project slug, enter the name of the project. Please avoid spaces or dots.
5. For Visibility level, select Private.
6. Select Initialize repository with a README and click on Create project.

Task 2

Follow the steps below:

1. Have a ready setup of VS Code with a connected GitLab account.
2. From the Get Started page on VS Code, click on Clone Git Repository. You can also clone a repository using Command Palette -> Git: Clone.
3. Click Clone from GitLab -> Select the created repository from the list. Then select the link with HTTPS.
4. Select a folder to save the files on your PC. Prefer saving them in the Documents folder. Then click Select Repository Location.
5. Once cloned, VS Code will ask whether to open the recently cloned repository in the current window or a new window. Select Open.

Task 3

Follow the steps below:

1. Create a new branch by clicking on the bottom left option (initially you will see Main written).
2. Select Create new branch. Enter the name of the new branch as "develop".
3. Add a new folder to the project by clicking on New Folder from the Explorer on the left side. Name the folder Blink.
4. Create a new file inside the folder named Blink.ino. The extension is important.
5. Paste the following code into the file:

// the setup function runs once when you press reset or power the board
void setup() {
  // initialize digital pin LED_BUILTIN as an output.
  pinMode(LED_BUILTIN, OUTPUT);
}

// the loop function runs over and over again forever
void loop() {
  digitalWrite(LED_BUILTIN, HIGH);   // turn the LED on (HIGH is the voltage level)
  delay(1000);                       // wait for a second
}

6. Click on Source Control from the left panel. Enter a commit message "initial commit".
7. Click on the Commit button. Next, click on Publish Branch.

Task 4

Follow the steps below:

1. Open your project online on GitLab.
2. Switch the branch of the project to "develop".
3. Locate the file Blink.ino.
4. Click on Open in web IDE.
5. Add the following lines in the code between delay(1000); and }:

digitalWrite(LED_BUILTIN, LOW);    // turn the LED off by making the voltage LOW
delay(1000);                       // wait for a second

6. Once done, click on Create commit from the left side.
7. Enter a commit message "update LED blink". De-select Start a new merge request.
8. Click on the Commit button.

For more information, please read the Workflow section of the tutorial.

Task 5

Follow the steps below:

1. In VS Code, go to Source Control.
2. Click on the Source Control menu (⋯) icon. In that, click on Pull. This will download the changes made from the GitLab server.
3. Open the file Blink.ino.
4. Replace the delay time from 1000 to 2000 for both delay functions.
5. Save the file and go to Source Control.
6. Enter a commit message, "Updated Blink duration".
7. Click on the Source Control menu (⋯) icon. In that, click on Push. This will upload the changes to the GitLab server.

Task 6

Follow the steps below:

1. Open your project online on GitLab.
2. From the left side menu, click on Merge requests. On the new page, click on New merge request.
3. On the next page, select the source branch, "develop", and in the target branch, select "main".
4. Next, click on Compare branches and continue. Enter the title for the merge request.
5. In the Description, provide brief information about the content of the new feature/part completed with this branch.
6. Change the rest of the options as per requirement.
7. Once everything is ready, click on Create merge request.
8. After this, another page will show up. This will show the details about the merge request. If everything is correct, it will show Ready to merge!.
9. Click on Merge to combine the code into the main branch. After this, the changes will be moved to the main branch.
10. Open the repository’s main page. Confirm whether the code is merged properly or not.

Task 7

Follow the steps below:

1. In VS Code, go to Source Control.
2. Click on the Source Control menu (⋯) icon. In that, click on Tag. Click on Create Tag.
3. Enter the required information such as Tag name and annotation message.
4. Click on View -> Command Palette.
5. Enter Git: Push Tags.

References

• GitLab Manage Projects