Week 01

During the first week we had time to understand the structure of the course and the place where it would happen. In my case it is Barcelona and Fab Lab Barcelona located in the Institute for Advanced Architecture of Catalonia.

Documentation seems to be the main focus of the course. This year GitLab is being introduced to the Fab Academy students. All of us have an account on GitLab and we have to use Git in order to document our learning process. From our GitLab repository the documentation travels to a web server, where it becomes accessible to the users of the World Wide Web.

I have decided (after the first week) to fill the documentation page of the first week with tutorials that could help others to set up their documentation website on GitLab. This is going to be Fab-Academy-specific and the following list is what topics we have to cover in order to get there.

  • Git
    • Installation
    • Configuration
    • Introduction
  • HTML
    • The HTML mindset
    • Setting up Sublime Text
    • Building basic website
  • GitLab
    • Setting up GitLab for your computer
    • Converting your website into Git repository
    • Uploading to GitLab and making it wisible on the web

This would be the very basic setup that one would need for a course. This can be covered in a week if one is thorough. This is why I would stop here for the first week. Look at the second week documentation to find out next steps to make your documentation process work for you instead of the oposite.

Git

I strongly suggest to use the command line version of Git. No matter how scary the command line might be, if you want to be friends with programming, begin mastering it now. Use Terminal on Mac OS X and Linux. Download Git command line for Windows or use Windows 10 Developer Mode.

Installing Git

There are different ways of installing Git for each operating system. On Linux (Debian and Ubuntu) you should open Terminal and run the following command.

sudo apt-get install git

It might be that sudo is not the way to go and you need to change your user to root before you can install software. If so, run the following and repeat the command above.

su root

On Mac OS X I would suggest you to use a package manager, such as Homebrew. With Homebrew installed, run the following command.

brew install git

If you do not want to install some weird package managers and what not, feel free to consult alternative options on Git website.

I have no direct experience with Windows 10, but I assume that you can use the Linux way of installation if you enable the Developer Mode.

Git Configuration

Before you start working with Git, you should set it up with your persona. Three things are important.

  1. Your name
  2. Your email
  3. Text editor

Git will use your name and email to sign the so called commits which can be explained as markings in time with information about what has been changed in the project you are working on.

Setting up text editor is important, as you probably do not want to spend too much time on learning something too ancient. By default the text editor is set to vim which is considered cool in the hacker community, but it takes a long time to master it. I suggest the GNU nano text editor, from my experience beginners have the least problems with it. Run the following commands in your Terminal to set Git up.

git config --global user.name "David Diva"
git config --global user.email "dave@rave.xyz"
git config --global core.editor nano

Using Git

You will have to remember a handful of commands in order to use Git for managing versions of your project. Start with creating an empty directory for your project.

mkdir my-git-project

Change the current directory to my-git-project.

cd my-git-project

Initialize Git repository. You will run this command only once, always starting a new project.

git init

It should print out the following. It means that Git has created an empty directory called .git in your project folder.

Initialized empty Git repository in /.../my-git-project/.git/

You should create a README.md file for describing your project. The .md extension means that it should be recognised as a Markdown file. It is a conventional way among programmers to communicate what the project is about.

touch README.md

Your project file tree should look as follows now.

my-git-project
└── README.md

Open README.md in your favorite text editor. I use Sublime Text and I usually open the whole project by issuing the following command. Then, double-click on README.md

subl .

Add some introductory content there. I try to be honest at all times.

# My Git Project

This is a Git repository to explain basics of Git.

Save the file and return to the Terminal interface. Type the following command.

git status

This is an important command to remember as it will let you see the current status of your Git repository. Now it will print out a message that there is a file that is not tracked by the Git system.

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    README.md

We are going to add it to the Git staging area. Staging area is an inbetween space between the current state of your project and Git version history. In order to record a version of your project, you will want to pick files to be included in the version first. In the staging area you keep a list of files to be added to the history. In order to add files to the staging area, run the following command.

git add README.md

This will add the file README.md to the staging area. It does not mean that we have a version entry yet. Type git status to check the status once more. It should return the following.

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

    new file:   README.md

Git shows you the list of files that are ready to be added to the version history. In order to add them (or commit) to the history, use the command below.

git commit -m 'Add README.md with basic description of the project'

Notice the so called flag -m which tells the git commit command that we want to add a message. After the -m flag we have to add a space and a message which should be enclosed in single or double quotation marks ("" or ''). The following should be the output.

[master (root-commit) 78b35ef] Add README.md with basic description of the project
 1 file changed, 3 insertions(+)
 create mode 100644 README.md

Try adding text to your README.md. I will split the sentence already there in two.

# My Git Project

This is a Git repository. It has been made to explain basics of Git.

Type git status, you will see that Git detects changes.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   README.md

Git also suggests possible scenarios (use "git add <file>..." to update). What we want is to commit another change.

git add README.md
git commit -m 'Split description sentence in two'

Now type git log to see the version history of your project. You should see the following.

commit c299ff48adf40a8a23c8bafbbeb6aea92923df44
Author: Krisjanis Rijnieks <krisjanis.rijnieks@gmail.com>
Date:   Sat Feb 3 22:04:54 2018 +0100

    Split description sentence in two

commit 78b35ef6c39ecfd10c1cc11a68c38b6530dce0b3
Author: Krisjanis Rijnieks <krisjanis.rijnieks@gmail.com>
Date:   Sat Feb 3 22:00:10 2018 +0100

    Add README.md with basic description of the project

What you see above are two entries in the version history. Note the commit c299ff48adf40a8a23c8bafbbeb6aea92923df44, these are unique commit identifiers. We can use them to roll back to a certain version in the project history. The rest should be self-explanatory.

The following is a simple workflow that you can use to version your project. I will explain more features in the GitLab part of this page.

  1. Make a change (add or edit a file)
  2. Use git status to see changes
  3. Use git add filename to add specific file you want to commit
  4. Use git commit -m 'Your commit message' to add changes to Git history
  5. Repeat

Lastly you need to update the remote part (the server) with content you accumulated locally. For that you use the git push command. A screenshot below (I avoid using screenshots in this section since a lot can be done by showing plain code, but here is one real screenshot).

Git push

I also added my-git-project to my Fab Academy GitLab account.

Conclusions

This week was mostly describing things that I already know. I have been using Git for more than 5 years now and used GitHub to clone, fork and contribute to open source projects. I have my own project called ofxPiMapper.

What I did and I asume is not going to be evaluated is that I helped many other students to understand Git, HTML and how to make it all work with the Fab Academy GitLab setup. One week can be enough for that if you avoid explaining CSS and JavaScript on top of HTML. One can build a responsive website by using plain HTML these days. Here is a good example (using a rather hateful language, but can make you smile if you have the right mindset).

It was hard to understand what is expected from us during the first week, thus in this page one might not find what is expected. One thing is the final project proposal. In order to see that, go to the Final Project page.