This is a brief introduction to the use of Gitlab, a front-end (web user interface) to Git. For general introduction to Git itself please use other resources. In this description, I used my user name xmeng and project name csci479-f13 as an example, readers need to replace them with proper names.

Gitlab is a distributed version control system. Gitlab provides a web user interface to using the core Git software. A user can share his/her software repository created and maintained by Git through Gitlab.

A general workflow for a user to use Bucknell's Gitlab is as follows. The detailed steps are in the section following this one.

• Log into the Gitlab at Bucknell using one's Bucknell computer account. To use Gitlab outside Bucknell, one can choose from many open Gitlab repository websites.
• Create a project (or projects) in the Gitlab
• Pull the project from Gitlab to user's Linux account.
• Use the Linux programming environment to develop the software.
• Commit the revisions to the software using the commit command in Git. Note that this step commits the revision to the local repository of Git on one's own file system, not to the shared repository over the web.
• Push the project revisions to the Gitlab website.

In a typical course context, a student would have to do the following steps to share her Git repository with the instructor and her teammates. The instructor can collect and grade student work then send back the comments to students through Git. The teammates would have access to a common code base.

Detailed Step-By-Step Instructions to Create Gitlab Repository

• Create an ssh (secured shell) key on your Linux system, if you haven't done so. Run the following command at your Linux prompt.

  ssh-keygen

  Take the default parameters as prompted by the command. When finished, you will see a file named id_rsa.pub in a directory called .ssh in your home directory. You will need to use this key (a text file) when creating the Gitlab account.

• Open a web browser with URL as
  https://gitlab.bucknell.edu
• Log into the Bucknell Gitlab website with your Bucknell credentials.
  
• Click the person icon at the top menu bar (next to the "+" sign) to open up your profile section. You will see at the lower right corner of the next screen, there is an "Add Public Key" button, click that button.
• Copy and paste your public key in the file id_rsa.pub into the credential section of the Gitlab user account. This file is in the directory .ssh in your home directory.
• Now you are at the Gitlab site of Bucknell. At the upper right side of the screen, you should see a "Projects" panel, where you can create projects on the Gitlab. We ask students create their own projects for the course to share with the instructor and their project teammates.
  

  Click the "+" sign (the title "New Project" appears next to the plus sign) to create a project. Call the new project "csci479-f13" (or other name when in different semester and different courses)

  Once created, you will see the project is assigned an URL similar to the following

  git@gitlab.bucknell.edu:xmeng/csci479-f13.git within Gitlab.

  where my user name "xmeng" and the course number "csci479" are used in the example. You should see your user name and your course number instead.

  An email will be sent to you from Gitlab to confirm that you have created a Gitlab project. You can ignore this email.

• The Gitlab project creation screen now shows a set of commands you should use to create a local copy on the local Linux file system. Execute these commands on your local Linux system first before taking further actions on Gitlab.
  

  Note that in the example commands below, I used my information for user name and email. You need to replace them with yours. The bold-face words mean the actual command you should type. The text followed by the colon, including the colon, if any, explains what the command means.
  

  • cd ~/: Change to your home directory, or a directory into which you'd like to put the course work.
  • git config --global user.name "Xiannong Meng"
  • git config --global user.email "xmeng@bucknell.edu"
  • mkdir csc479-f13
  • git init
  • gedit README: Type some message in the README file, e.g., "This is the directory for CSCI 479 work." and save the file.
  • git add README
  • git commit -m "Course directory commit."
  • git remote add origin git@gitlab.bucknell.edu:xmeng/csci479-f13.git
  • git push -u origin master
  Now you have a synchronized copy of csci479-f13 on both the local Linux system and the remote Gitlab server.
• Share this project "csci479-f13" with the instructor by specifying the instructor (xmeng@bucknell.edu) as one of your teammates. To add the instructor (or others in your team project) as your teammember, click the "Team" tab next to the "Show" (i.e., project home) tab, you can choose users from there. You should classify the instructor as the "master" of the project, the same as you are so that the instructor can write comments back to you in the same directory.
  

  Note that this permission has nothing to do with the file permissions on your local Linux (or Windows) file systems. The permissions on the Gitlab website are used only within the Gitlab context, not even your local Git copy.

How to Add Directories And Files to a Gitlab Project

Now that you haven owned a Git project both on the Gitlab server and on your local Linux account, you can create more directories and files under the Git structure and share them with your teammates or your instructor.

The basic idea is that you can create, revise, or remove any files under the current local Git tree, e.g., under your csci479-f13 directory. When you revise any existing files or create any new files, you should manually add the them to the local copy of Git by using the command git add and commit to the local Git copy by using the command git commit. You can synchronize the repository with remote (web) Git server by using the pull (from the Git server) and push (to the Git server) commands.

Here are a few commonly used commands to manage your Git repository.

• git add file(s): Add files or directories to the local Git repository. This should be done any time a new file or directory is created.
• git commit -m "message": Commit any changes to the files and directories on local Git repository. This should be done often so the changes are "committed."
• git push: Push the local copy of the Git repository to the Git server and synchronize between the two. This should be done whenever you are about to leave the current computer system or you need to share the files with your teammates or your instructor.
  

  Note that in order to push (or pull) a project, you must have either created the project (e.g., using the git init command), or cloned the project (e.g., using the git clone command, see below).

• git pull: Pull a copy of the project from Git repository server to the local file system and synchronize between the two.
  This should be done whenever you log into a local Linux system and are ready to work on the project.
• git clone git@gitlab.bucknell.edu:<user-name>/csci479-f13.git, where <user-name> should be replaced by a real user name, e.g., xmeng
  

  Doing so creates a copy of csci479-f13 project on your local file system in a directory other than your original directory. You can use this command to "import" a project from Gitlab that was not originally created by you (e.g., by your teammates.)