Gitlab - Getting Started

Git

Git is a version control system that can be used to keep track of your files (programming code, but also other files as well).

Two of the most popular installations of git (as of 2020) are github and gitlab. When Microsoft purchased github, it became fashionable to prefer gitlab. Github allows for projects to be hosted on their servers. Gitlab allows for hosting either on their servers or to run a local installation of gitlab on ones own servers.

Of late, we have hosted projects using gitlab either on gitlab's servers or on ISU's local installation of gitlab.

Account Setup

On gitlab.com - Account setup on gitlab.com is just like any other website. You create a free account, choose your username/password, etc. The account is yours and is not tied in any particular way to ISU. You can give access to your projects in much the same way as you give access to files on google drive, onedrive, dropbox, etc.

On gitlab.indstate.edu - ISU's local installation of gitlab is at https://gitlab.indstate.edu/. For this system you use your ISU portal id and password. You do not need to create an account. The first time you login into the system, it initializes an account for you. CS courses and ISU CS projects in general tend to use ISU's local installation because we can tie access based on course rosters, etc.

Getting Around

Whether you are using gitlab.com or gitlab.indstate.edu, the functionality and "how to get around" is about the same. You have two main methods for using either.

Web browser interface

You can view projects within your web browser. How to get around is fairly intuitive - as is the case with any web page, you look around and click around to see what different things do. When you have something specific you want to do but don't see how to do, you ask the internet or ask your instructor (and we may update this wiki to give instructions on how to do it).

Terminal interface

Git allows for downloading/uploading/etc. files in your projects from the terminal. In order to do this, you need to (a) have a git client installed on your system, (b) understand the terminology that git uses for keeping track of files and the steps in using git to download/update/upload files, (c) make it so.

Some reading material about using git - https://www.tutorialspoint.com/git/index.htm

Workflow

A common use case is that you will need to download someone else's (e.g., instructor's) gitlab project, create your own version of some part of the project, test/debug your version of the project, eventually put in a request to update the main project with your code. The steps involved in that workflow.

Clone - To download the current version of the project you (a) browse in your terminal to the directory where you want to have the project code, (b) run git clone url_to_project

Branch - If a branch has already been created for you, then you can set that as your active branch by running git checkout branch_name. If a branch has not yet been created for you, you run git branch branch_name to create a new branch. In either case, you have a branch of the project to work within.

Do your work - You work on your files locally - test, debug, etc.

Stage/Commit/Push - To save your work to the remote server, you need to stage, commit, and push. You can stage/commit batches of changes, or do a stage/commit for each discreet task accomplished. If you are working in some_file.txt, you would run the following sequence of commands.

git add some_file.txt  # this "stages" the file to be part of the next commit
git commit -m "Some updates to the file" # This commits, will be a permanent record of this version of the file
git push               # sends all committed changes to the remote server

Note that the push will likely ask for login information to the remote server. Note that if you want there to be a record of a particular version of a file, you need to stage/commit the file. It is the commit'ed versions of files that are stored permanently.

Pull - To pull/download updates that have happened (by others), you use git pull.

Merge - When you ready to have your changes merged in to the main branch of the project, ask the owner of the project to check your branch. When the owner is ready for it, the owner can run the following commands.

git branch main        # owner is working in the main branch
git merge branch_name  # merge your branch into the main branch