Using git and GitLab

Access
GitLab @ UCSC

This page lists shortcuts for common tasks using git and GitLab @ UCSC.

Using this page

Commands are in gray boxes, like this: cc -O3 -c program.c Note that -O3 is in italics. This means that it's optional—sometimes you'll need it, sometimes you won't. program.c is in red, which means that it's a placeholder for your own value, in this case the name of your C file. A value that's both italics and red is both optional and a placeholder.

While you should read the whole page to learn how to use git, there are some things that students often miss. To help you, we've highlighted important sections in yellow.

Sections in green boxes like this one are more advanced concepts that you may ignore unless your instructor has asked you to read them.

Basic concepts

The basic unit of stuff in git is a repository. A repository consists of a single directory tree, as deep as you'd like to make it.

Operations

All operations in git are done within a single repository (we'll omit the complication of having submodules for now). The basic operations you'll need to be able to do are:

We'll cover each of these operations in detail below.

Commits

A commit is a set of changes that are committed to the repository in a single command. This can be changes to a single file, or changes to multiple files. The repository can reproduce the exact state of any commit that's been made in the past at any time, and can allow you to time travel to a different commit. In addition, there are tools that can show you the changes between the repository's current state and its state at any previous commit. This is very useful for seeing what changes you made that improved things (or made them worse). It's also useful for trying things that might not work: you can always go back to the last working version, so you can delete code rather than commenting it out.

Branches

Coming soon.

Access method: https or ssh?

You can access GitLab @ UCSC using either https or ssh. There are advantages to each approach. You can use both approaches to talk to the server, even for the same server repository. However, when you choose a particular approach for a repository that you've cloned to your local computer, git will use that method for all future interactions between that particular local copy and the server.

For both SSH and HTTPS, you can get the appropriate string as described above.

SSH (the preferred method)

ssh is the preferred access method, since it doesn't require you to specify a username and password when you interact with the server. You'll need to generate an ssh key pair and upload your public key to the server. You may, of course, use an ssh key you already have for this purpose. Also, you may upload multiple ssh keys if you like—perhaps you have different keys for different computers.

Uploading your SSH key

To upload your key, first navigate to the Settings screen using the pulldown menu in the upper right of the window. Then, select the SSH key setting. This will bring up the SSH key screen. Paste your SSH public key into the key box, type in a name for it in the title box (the name doesn't matter; it's just there so you can differentiate multiple keys if you have them), and then press Add key. Congratulations! You now have an SSH key uploaded to GitLab @ UCSC!.

Using SSH

Using SSH, your command to clone a repository would look like this: git clone git@gitlab.soe.ucsc.edu:cmpe000/fall17/cruzid.git Note that the user (the part preceding the @) is always git, not your CruzID.

Using HTTPS

https authenticates using your username and password on every interaction with the server. This access method is useful if you don't have an ssh key on the computer, as might be the case if you're on a lab computer. If you want to avoid typing your username each time, you may add your account (CruzID) between the // and gitlab in the URL, like this: git clone https://cruzid@gitlab.soe.ucsc.edu/gitlab/cmpe000/fall17/cruzid.git

Workflow

Stage 1: get a local copy of your repository

You should only need to do this once to get a copy of a repository on your local computer. However, if you want a second copy (perhaps you corrupted or deleted the original), you can follow these instructions again.

  1. Log into your account on GitLab @ UCSC.
  2. Navigate to Projects in the menu on the upper left.
  3. Click on the project you want a copy of from the list of projects that's displayed.
  4. In the middle of the page, there's a box with a pulldown to select either SSH or HTTPS. Select the one you want to use.
  5. Click the icon next to the string to copy the URL to your computer's clipboard.
  6. Clone your repository using a command (in a terminal window) that looks like this: git clone git@gitlab.soe.ucsc.edu:cmpe000/fall17/cruzid.git or: git clone https://cruzid@gitlab.soe.ucsc.edu/gitlab/cmpe000/fall17/cruzid.git If you use HTTPS, you'll be asked for your password, which is the same as the one you use to log into GitLab @ UCSC web interface. Note that you may have to add cruzid@ immediately before gitlab.soe.ucsc.edu for this to work. Otherwise, gitlab.soe.ucsc.edu has no idea which username to use to clone your repository. (Yes, the repository name may be the same as your CruzID, but it could be anything—GitLab doesn't know it's the same.)

Stage 2: work on your code

Repeat the following steps as necessary. You should be committing relatively frequently; there's no penalty to doing so. It's often useful to ensure that your code works before committing it, but you'll often want to violate this rule when you're getting the initial code written.

  1. Work on your project, repeating these edit (and add) / commit steps as often as you want before moving on to Steps 2 and 3.
    1. Make changes to files in the repository. If you add new files, make sure you tell git about them with git add.
    2. commit your changes to the local repository.
  2. [Only do this step if you're working with others!] fetch others' changes to your repository and rebase your code to include their changes. This might create conflicts if you're both editing the same files. If so, resolve the conflicts and commit locally again before pushing your changes.
  3. push your changes to the remote repository.

Stage 3: submit your code

This part is instructor-specific; please check with your instructor on how to do this. However, there are some common approaches that are used. Please make sure that your most recent commits are pushed to the server! If you don't do this, nobody can see the commits you've made!

Submit commit ID online
For this submission method, you'll need a commit ID to turn in online. A commit ID is a string of 40 (hexadecimal) characters that looks like this: 06e6735071c3de04f42bf1e0dcfbec7d4c077e69. You can easily get it by logging into GitLab, navigating to your project, and clicking on the circled icon (we added the circle) to copy the full commit ID to your clipboard.

If you want to submit a commit other than the most recent one, click on Commits to see a list of commits you've made:

This will bring up a list of commits that looks like this. Click on the icon as above to copy the commit ID you want to the clipboard.
Last commit before due date
With this approach, the last commit before the due date contains the files that are graded. No special commands are needed; just make sure you're committing your files regularly and pushing them to the remote repository.
Commit a file indicating the assignment is ready
In this case, you'd create a file (perhaps using a name that the instructor provides), use git add to add it to your repository, and then commit your change.
Tag a commit indicating the assignment is ready
This approach is similar to the previous one, but doesn't require creating a new file. Instead, you issue a tag command labeling a particlar version (usually the current one) as the one you want to submit. You then need to push this tag to the remote repository.

Commands

clone

The clone command downloads a copy of a repository to your local machine, and looks like this: git clone git@gitlab.soe.ucsc.edu:cmpe000/winter18/cruzid new_name

Once you've done this command, you'll have a copy of the repository in the cruzid directory where you ran the command (if you supplied new_name it'll be called that instead). The repository remembers where it was cloned from, which'll be useful later on.

This will fail if you don't have permission to clone cmpe000/winter18/cruzid. As a student, you likely only have permission to clone your own repositories, so you should make sure that cruzid is replaced with your actual CruzID.

add

Now that you have a local repository, you'll probably want to add new files to your repository. Do this as follows: git add file1 file2 You can add as many files as you like, and can also use shell wildcards (git add never sees the wildcards because of expansion). Once you've done this, git will track changes to these files as well as those already being tracked. However, this tracking won't happen until you commit your changes. If you don't explicitly use git add file, git won't know about your file, and won't commit it. Make sure you add all files (and only those files) you want included in the repository.

DO NOT USE A COMMAND LIKE THIS: git add *. You don't want most of the files in your repository. You may want to create a .gitignore file so that you don't accidentally add certain files. There's lots of documentation on gitignore available online.

commit

So you've made some changes. You probably want to commit them, so the changes are recorded in the repository. Do this with: git commit -a -m message This commits all (the -a option) of the changes you've made to tracked files. If you don't specify a message on the command line, git will bring up an editor for you to enter a commit message. Your message can be any format you like; however, convention says that the first line of the message should succinctly describe the commit, followed by a blank line, followed by a longer description, if needed. If you put the message on the command line, you'll probably need to enclose it in quotes so that the shell treats it as a single argument.

These changes are now recorded in your local repository, but they are not saved in any remote repository, including GitLab @ UCSC. To save them remotely, you have to push them.

push

Once you've made changes locally, you'll probably want to make the remote repository reflect your changes. Do this with the following command: git push --all This makes the remote repository (by default, the one you cloned from) include the changes you've made. You don't neeed to push after each commit, but your changes won't show up remotely until you push. The commit times for each commit aren't affected by when the push is done, so if you commit ten times over the day and only push in the evening, each commit will still have its original commit time on the remote repository.

The commits you've made locally will only be visible to your course staff after you've pushed them to the server, so make sure you push regularly, and before the assignment is due. You can check the status of your repo on the server if you want to be sure that the server got the latest commits you pushed. Just log into GitLab @ UCSC, select the project you want to view, and see what the latest commit is.

If you're sharing a repository, there might be errors. Suppose someone else made changes and pushed them to the remote before you did. You have to integrate these changes into your own repository before the remote is willing to accept your changes. This shouldn't happen if you're the only one making changes (from a single repo), but might happen if you're working as part of a team.

tag

You can use this command to assign a symbolic name to a particular commit in your repository. By default, this is the most recent commit, but you can tag any commit you want. The command looks like this: git tag -a tag_name -m tag_message While both tag_name and tag_message can be strings (enclosed in quotes, of course), we recommend that you use a single word, possibly including non-alphanumeric characters, for tag_name. For example, you might do: git tag -a asgn1-v0.9 -m My code is nearly working! to tag a particular commit. By default, git push doesn't send tags to the server; you need to run git push --tags to send your tags to the server.

So why would you want to use tags? They're useful for quickly finding a particular commit (you can list current tags with git tag). They can also be useful to annotate your history of commits, such as you might want to do to indicate that a particular commit is the one that you want the grader to consider (ask your instructor if this is the way you should mark assignments for submission). Tags may be modified or deleted locally, but GitLab @ UCSC is configured so that, once a tag is pushed to the server, it may not be modified or deleted. There's a good reason for this: once a tag has been pushed to a remote server where someone else such as a collaborator or the grader has seen it, you shouldn't be able to change the tag.

fetch

In order to integrate changes on the remote into your code, you have to pull them into your repository: git fetch --all
git fetch --tags
The --all option says that you want to fetch all of the changes made to the remote repository, not just those that affect your branch. This is always a good idea unless you have a really big repository and only want the changes that affect your code. Using the --tags option fetches all of the tags committed by others. After you fetch, you should probably rebase your code.

rebase

You can integrate changes on the remote that you've fetched by using this command: git rebase Don't worry; your changes will be included as well. If git has two sets of changes (remote and local) to the same lines of code, it'll tell you that you need to resolve the conflicts manually. However, if the changes are to different parts of the code, this operation succeeds. Note that there's no guarantee that your changes merged with those someone else made actually results in a working system.

checkout

branch


Last modified (none) by Ethan L. Miller (elm«at»ucsc·edu)