First week - Setting up git

I have multiple years of programming experience, 4 of them paid. I already knew how to use git, so most of this stuff did not use any tutorials. It was just me doing stuff that I had done many times before. I had not used Gitlab previously, so that was an interesting experience. Still couldn’t see a reason to switch from Bitbucket, but Gitlab is nice.

Git is a version control system for programming projects, and for code especially. It enables tracking history and group work by combining the changes made by other people. Sometimes the automatic combining does not work, and it has to be done manually, but that mostly only happens when multiple people try to edit a single file at once. Git works by storing the code in multiple repositories: often one of them is the central repository and every programmer has their own repositories. The code is moved from programmer to the central repository and back, when needed. Git also supports branching to enable multiple teams to work simultaneously on breaking changes, without affecting other teams work.

Setup ssh-key to gitlab

Gitlab, or at least the git setup used by Fab Academy, does not allow for password based authentication. It has lately been frowned upon on almost all use cases, and almost all nerdy sites have used to ssh-key based authentication. Some of them have even disabled passwords altogether. SSH keys are nice, as they do not require user to know anything, are secure and are easy to remove from services if they are somehow compromised.

Commands:

ssh-keygen -t rsa -C "jonimatiasrajala@gmail.com" -b 4096
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/jonirajala/.ssh/id_rsa): gitlab
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in gitlab
Your public key has been saved in gitlab.pub

Moved the generated keys (named gitlab and gitlab.pub) to .shh folder. By drag and dropping it after I opened the window with open ~/.ssh.

Configured the key in ./ssh/config file.

Host gitlab.fabcloud.org
  AddKeysToAgent yes
  IdentityFile ~/.ssh/gitlab

Uploaded the contents of the public ssh key (gitlab.pub) to gitlab in SSH Keys under user preferences.

Clone the repository

Ran the following command in the repository:

git clone git@gitlab.fabcloud.org:academany/fabacademy/2024/labs/oulu/students/joni-rajala.git

At this point git gave a warning about updating the default merge settings. The warning was ignored, as the expectation is that this repository is only updated from one computer, there is no need to pull changes. So the merge settings were not updated, mostly for laziness.

Edit the repository

Create gitignore file with following content to remove additional MacOS files

.DS_Store

Run commands to push the .gitignore (and other changes). .gitignore needed to be added separately, as bash does not expand the wildcard * to include dot files (like .gitignore).

git add *
git add .gitignore
git commit -a -m "I don't remember what I wrote here"
git pull
git push

Git commands

Git works by storing the code in three layers of code. In addition to these, these are different states that the files can be in each layer.

Layer	Description
Working copy	The folder in your file system
Local repo	The repository that you have on your system
Remote	The remote repository that you have connected, most often containing the master copy that all developers use

Git has many different commands that do different things. The most common commands are part of the pull-commit-push loop, that needs to happen whenever you want to update the master repository.

Some of the common commands are:

Command	Description
status	Shows the status of the local repository
add	Adds files to the list of tracked files that the git follows in you working copy.
commit	Commits the changes to the tracked files from working copy to local repository.
push	Pushes all commits from local to remote.
pull	Pull changes from remote to the local repository, tries to merge the changes and updates working copy to match.
fetch	Like pull but does not merge.
branch	Creates and manages new branches.
checkout	Changes to another branch or to previous commit.
reset	Discards changes in the working copy.
stash	Discards changes in the working copy, but saves them so they can be retrieved later.

Setup the website with markdown

I setup the website to use mkdocs to support markdown.

Downloaded markdown template from https://gitlab.com/fabacademy_oulu/students_template_site. Markdown is nice, because it allows me to write websites like I would write normal text files, without the need to hassle around with tags and formatting. But at the same time it allows me to use those if I need them. Markdown has its own syntax for simple formatting things like tables, images and headers, but those are extremely readable in both markdown and html forms, whereas the html code is jumble of tags and additional info.

The negative side of using markdown is that it needs to be compiled to html, so you cannot see the end results as easily as you could with HTML, and the markdown compiler is not as picky about its errors as code compilers are, so it will compile your incorrect markdown to html, but the end result will probably be unreadable mess.

Sometime around here, created a file called simple_document.md and put it in the root of the repository.

Open the zip to the folder next to the local git working copy.

Delete readme file from the template. It already exists in the repository.

Copy files

for $file in *; do mv $file ../joni-rajala/$file; done

Copy dot files. No .gitignore, I already have that.

mv .gitlab-ci.yml ../joni-rajala/.gitlab-ci.yml

Remove the public folder from the repository. Add all, commit, pull push.

cd ../joni-rajala
git rm -r public
git add *
git commit -a -m "Installed template for mkdir websites. Removed public folder."
git 

Setup development environment

Open Visual Studio Code.

Open the folder with the working copy of the repository.

Add .vscode folder to .gitignore, which now looks like this:

.DS_Store
.vscode

Update website

Replaced the avatar-photo.jpg with an image with my favourite photo of me.

Updated the data in mkdocs.yml to match my personal information. That file contains the settings how the mkdocs should compile the file, including, but not limited to, page navigation, header information, installable addons, style data (including where the css files are), and general site data. Now the beginning of the file reads:

site_name: Projects of Joni Rajala
site_description: Adventures in Fabrication

site_author: Joni Matias Rajala

At first I started using the site as recommended by the template and the mkdocs default behavior, but soon I updated the site to work a bit better. You can read it from here.

Gitlab has setup some kind of container that does the markdown compiling and publishing automatically after each push to the main branch. Container is basically a virtual computer inside a computer, that can be easily started, stopped and halted. The container is defined in .gitlab-ci.yml file. That file install all the required dependencies to the container, and runs the scripts for markdown compilation and website publishing.

Repository structure

Everything website related in the repository is stored in the docs folder. Under that folder I have folders for different tabs that are used for navigation. Those folders are about, assignments and projects. Those folders include the markdown files for each webpage. docs folder also includes the file index.md, which contains the markdown for the home page.

There are also folders for source code (src), images (images), videos (videos) and other files (files). files is subdivided into weeks, and assignments also has a subfolder steps for weekly subprojects. assignments folder also includes the file assignment_index.md which is used as the main landing page when the assignments tab is pressed.