IntelliJ Git Overview

Preface

This page will give a brief description of how to use basic Git features in IntelliJ. For an introduction to Git, consult the Git overview page first.

There are many tools and features not covered in this guide, so feel free to explore a bit! (However, you may want to have some familiarity with Git before you do so, because it's possible to completely mess up your local repository with Git, and if you accidentally you push your changes to GitLab, the remote repository as well. In general, if you're not sure what something does, and it doens't seem like a visual/display option, you should consult IntelliJ/Git documentation before trying it.)

Also you may use the Git command line interface or another GUI if you prefer; we won't provide guides for those though, and the course staff may not be able to debug any issues you run into with them.

Cloning a repository from GitLab

Before you can start working on project assignments, you'll need to get our code. Here's how you clone your assigned GitLab repository onto your machine in IntelliJ.

If IntelliJ is open on the welcome screen, you can just click "Check out from Version Control" option.

Otherwise, if a project is already open, you can click "VCS" > "Checkout from Version Control" > "Git".
Afterwards, a window will open where you should enter the URL of your repository from GitLab and a directory to save the cloned repo into.

Note that this URL is NOT just the URL of the webpage you visit; instead, get this URL by navigating to the home page of your repository on GitLab ("Project" > "Details"), then clicking the copy button on the right side of the text box labelled "SSH". The URL should look somewhat like the one in the image above. (If the text box is labelled "HTTPS" instead, you'll need to click the dropdown to select "SSH" before copying the URL.)
If you've cloned one of our homework assignment repos correctly, IntelliJ should pop up with another window asking whether you want to open the project you just cloned.

If you're using the project-per-assignment workflow, it should be safe to choose "Yes" here to open the project. (This may cause errors if someone else has accidentally committed their project config files, in which case you should import the project as described in the project import guide.

If you're using the single-project workflow, you should choose "No" and proceed to add that code as a module in your project, as described in the project import guide.

Note: if you're just setting up your IDE (i.e., doing homework 0), then you may stop reading here and come back when you've made some changes.

Pulling changes

If it's been a while since you last worked in your local repository, you'll want to pull changes from GitLab before starting again to minimize the chance of merge conflicts. The pull functionality in IntelliJ is somewhat hidden in the menus:

Click "VCS" > "Git" > "Pull..."
In the window that opens, click "Pull".

If you're using the single-project workflow and you already have multiple modules in your project, you may need to first select the proper "Git Root" (i.e., the directory containing the assignment repository).
If there are changes in both the local and remote repositories since your last pull, Git will attempt to automatically merge the changes. If the automatic fails, a "Conflicts" window will pop up; consult the merge conflicts section for more details. Otherwise, you're ready to start coding!

Comitting changes

After you've made some changes in the code, you should commit your changes from your working directory to your local repository.

Before we begin, note that IntelliJ marks local changes right in the editor:

The colors to the right of the line numbers and @ symbol denote changes in your working directory (compared to your local repository). The green highlight marks an added line, the gray right-pointing triangle marks removed lines, and the blue highlight marks a changed line.

These markers are very useful for checking that you haven't accidentally modified code that you were not supposed to modify. You can also list all changed files by opening the "Version Control" tool window and selecting the "Local Changes" tab:

(If you're using the single-project workflow, you may want to use the "Group By:" selector in the left-side toolbar of that tool window to group changes by module.)

It may be useful to show the diff pane in this tool window, which will show a side-by-side comparison of the file before and after your local changes. (The button for this is in the left-side toolbar of the tool window, at the very bottom—it's actually hidden in the overflow menu in the screenshot below.)

To commit changes:

Open the "Version Control" tool window and select the "Local Changes" tab. Then, click the green check mark button on the left-side toolbar in that tool window.
A "Commit Changes" window should open. In this window, select the files you wish to commit and enter a commit message to describe your changes. This window also includes a diff viewer that allows you to view local changes.
At this point, you may want to review the "Before Commit" options in this window. These options control what automatic checks and changes IntelliJ will make before committing your code. The relevant options for our class are enabled in the image below.

You aren't required to enable any of these, but...
- We strongly recommend enabling at least the Checkstyle scan.
- The "Reformat code" can also be useful for ensuring that your code conforms to our style, but could also ensure that your code doesn't conform to our style if your IDE is configured incorrectly.
- The "Perform code analysis" option will also run Checkstyle, but it will group those errors with any others in the project, so it's easy to accidentally ignore them. (Also, this option is just annoying in general since it will pop up a dialogue box if there are any warnings in the code.
- The "Check TODO (Show All)" option may help make sure there aren't any TODO's left in code.
When you're done, click the "Commit" button in the bottom right to finish committing. If you want to commit and push at the same time (which is reasonable for small projects like ours, but is less useful in large projects), you can also use the dropdown arrow and choose "Commit and Push" instead.

Pushing changes

After you've committed some changes, you'll probably want to push them from your local repository to GitLab. This functionality is again hidden in IntelliJ's menus:

Click "VCS" > "Git" > "Push..."
The window that opens will show a preview of all local commits that you will push to, the remote repository. In this window, click "Push".
If the push succeeds, then you're done, and you can stop here.

If your push fails, it is likely that someone else has pushed changes to the remote repository since the last time you pulled from it. In this case, you'll need to merge in the remote changes before trying to push again. The dialogue box that appears in this event will look like this:

Click "Merge" to attempt to pull and attempt automatically to merge the remote changes. If there are any conflicts that cannot automatically be resolved, the "Conflicts" window will open; see the merge conflicts section for more details.
After completing the merge, we recommend checking that all relevant code still works properly. You should check this even if the merge completes automatically: an automatic merge just means that the changes were in different parts of the file—not necessarily that the automatically-merged version of code is correct.
After you've made sure your merge is correct, you'll need to tell IntelliJ to push again by starting over from step 1. If you merged properly (and nobody else has pushed again after you merged), the push should no longer be rejected.

Handling merge conflicts

Fortunately, IntelliJ has a very nice UI for resolving merge conflicts. It can seem daunting at first since there are so many panes, but it actually makes a lot of sense once you understand what it's trying to do.

We'll direct you to the IntelliJ documentation for this part, although we'll note that the conflicts window looks slightly different than in their screenshot for whatever reason:

Here is the IntelliJ documetation for its merge conflict UI. The page is fairly straightforward, but to recap: the merge conflict resolver window will display a three-way comparison between the three versions of code: local changes, final result, and remote changes. You'll need to manually accept or reject each conflicting change from the local and remote repositories to update the result in the middle pane. When you've accepted or rejected every change, click the "Apply" button to finish merging the changes in that file; repeat this process for each file with conflicts.

Note that if you aren't careful in this process and cancel the merge (e.g., by clicking "Abort"), your repository may be left in a half-merged state, which will prevent most Git functionality from working properly. If anything goes wrong, we recommend coming in to office hours for help unless you're confident in your Git knowledge—Googling and trying random things may make things worse if your problem doesn't exactly match the solutions you find, and it tends to be difficult to debug these issues online on the discussion board.

Other tools

Again, there are many other Git features not covered in this guide for the sake of brevity. You can see the IntelliJ documentation for more details.

One particularly nice feature is the Log tab in the Version Control tool window, which displays a visual representation of the commit history in your Git repositories: see this page for an overview or this page for the full documentation