コンテンツにスキップ

Version Control: Gitlab#

  • Authors: Rico Kanthatham, Georg Tremmel
  • Created: 1/20/2020, Last Updated: 1/27/2023

Info

FabAcademy uses git for version control to record all of your coursework. The GitLab FabCloud is a webservice for managing server space and hosting your repositories and website.

Version Control#

…is a method to track and record changes made to your documents allowing you to revert back to an older (historical) version if needed. Most of the time in Fab Academy, reverting to a previous version is not necessary. But these “backups” will become valuable if your laptop or hard drive become broken, or your most recent files becomes corrupt.

“Gitlab” is a version control, cloud storage service used to store and track changes to your Fab Academy coursework documentation and supporting files (images, 3D models, code, etc.).

Gitlab Terminology - The cloud storage of your Fab Academy documentation is called a “Cloud Repository” - You will have a copy/clone of the Cloud Repository on your personal computer/laptop called a “Local Repository”

Gitlab Workflow Overview - The “Cloud Repository” and “Local Repository” must be kept in sync - Typically, you will save documentation work into your “Local Repository” then upload changes to the “Cloud Repository” to update it and keep them both in sync.

Version Control Tools: GitBash, Atom, Markdown#

While there are many many tools that you can use to upload your Fab Academy documentation to your cloud repository for publishing as your Fab Academy webpages, the simplest and easiest combination is comprised of Gitbash, Atom & Markdown.

Git…is a terminal program used to instruct Git to perform specific actions, such as upload or download…into the GitLab FabCloud service. Atom…is an Integrated Development Environment (“IDE”), a text editing software designed to make coding more efficient. Atom is one of many popular IDEs. Another popular and recommendation IDE is Visual Studio Code. Markdown…is a ‘markup’ language that is easy to read and write (in English)…and easily converts to HTML for webpage publishing.

The Weekly Documentation Workflow

  1. Within the Atom (or another) IDE, use the Markdown language to write your Fab Academy “Documentation” (including specific symbolic syntax that will allow for HTML conversion)

  2. Then use Git to upload your Markdown “Documentation” from your “Local Repository” to your “Cloud Repository” for automatic translation to HTML and publishing as your personal Fab Academy website pages

Hint

Simply stated, Atom & Markdown will be used for Local Repository editing, while Gitbash will be used for uploading documentation changes to the Cloud Repository for web-publishing.

Gitbash Overview#

Gitbash is a software for Windows. On MacOS or Linux, just use the Terminal.

Gitbash is terminal/shell program that functions by means of command line instructions…used to upload changes made to files in your “Local Repository” (a file folder located on your PC) to update your Fab Academy GitLab “Cloud Repository” (located on the Fab Academy server).

Note

Note for MacOS users: the Gitbash terminal program is not necessary and git commands can be done in the simple terminal.

An introduction video to using Gitbash to upload changes can be found here

Basic Git Commands#

The 6 most useful Git commands for Fab Academy students:

  • git pull
    • pulls down (downloads) the current cloud repository to update the local repository
  • git add .
    • tells Git that you wish to add new files from local to cloud repository
  • git status
    • checks the status of the local repository…if new files exists to be added to the cloud repository
  • git commit -m “(add your comment here)”
    • tells Git that you want to sure that you want to send the new files in the local repository to the cloud repository
    • includes a message to remind you what changes you are committing
  • git push
    • sends committed files from the local repository to the cloud repository
  • CTRL + C
    • cancels the active terminal command…resets the command line to an empty prompt

Git commands for initial setup and SSH encryption key

  • git config –global user.name “your_name”
    • registers your user name
  • git config –global user.email “your_email”
    • registers your user email address
    • email address should be the same as your Gitlab registered email
  • ssh-keygen -t rsa -C “your_email”
    • generates your personal SSH encryption key
    • same email as user email
  • cat ~/.ssh/id_rsa.pub
    • confirms generation of SSH encryption key

How to add your SSH Key to the FabCloud#

https://docs.gitlab.com/15.8/ee/user/ssh.html

Checking if your SSH Key works#

Anywhere In Terminal 

$ ssh -T git@gitlab.fabcloud.org
Welcome to GitLab, @georg.tremmel!

Atom#

Atom is an Integrated Development Environment (IDE) program. It is an enhanced text editor that can be used for writing Markdown documents, as well as write programming code. There are many IDEs available to choose from (Visual Studio is a highly recommended alternative), but Atom was developed by GitHub, it features embedded Git control and allows for smooth communication with GitLab.

An introduction video to using Atom can be found here

As of 2023 Atom has beend sunsetted, that means it’s still working, but it will no longer be developed and updated.

Markdown#

Markdown is a simple and highly efficient text editing and formatting language…that generates HTML script automatically. Markdown documents uploaded to the cloud repository can be read as HTML and create a webpage. It is the recommended Fab Academy documentation tool for its time-saving simplicity.

An introduction video to using Markdown can be found here