Project 1.1: IntelliJ and Git

Go to bitbucket.org and create an account for yourself based on your Carleton email address. (It's important to use an address ending in “.edu” so you will get a free, unlimited academic account.)

Log in to your Bitbucket account, go to Repositories→Create repository and create a Git (not Mercurial!) repository named EncodingHelper. Keep it private.

A repository is essentially a folder in which you can store whatever files and subfolders you want. What makes a repository more than a folder, however, is that the version control system (Git, in this case) keeps track of all the changes that get made to the files in the repository. This saving of history makes it possible for you to retrieve old work, track down the time when a bug was introduced (and who introduced it), collaborate on a project with a team of programmers, easily back up your work, etc., etc. Version control systems are a bit of a hassle to learn for the first time, but they're indispensable programming tools and unquestionably worth the effort.

You can get Git here. It's possible that you already have Git on your computer, but you would probably know it if you did.

Once you install Git, you'll be able to use it from the command line. For many people, that's sufficient. However, there are some benefits to using a GUI Git client, too. Since we'll be using Bitbucket to host our Git repositories, I recommend that you take Bitbucket's advice and install Atlassian SourceTree, which integrates very well with BitBucket. IntelliJ also has Git integration, so you could hold off for now and try that out instead. It's all up to you.

For the rest of this document, whenever there's need to show a Git operation, I will show you the Git command-line version of that operation. If you're using SourceTree or IntelliJ's Git features or any other Git client, you'll need to figure out the equivalent operations in your client.

Right now, your EncodingHelper repository is stored only on the Bitbucket server. To add files to it, you'll need to “clone” a copy of the repository onto your own computer. You will then add files to your local copy of the repository and push your changes back up to Bitbucket.

Bitbucket gives you some setup instructions right after you create a new repository, and they work just fine, but there's a simpler way to make your clone.

First, make sure you've got a directory where you'll work on stuff for this class. Each project will have a directory of its own within this. Change into this directory on the command line, and then:

git clone https://YOUR_USER_NAME@bitbucket.org/YOUR_USER_NAME/encodinghelper.git EncodingHelper

Of course, replace YOUR_USER_NAME with your actual username on Bitbucket.

(Note that Bitbucket instructs you to use git@bitbucket.org:YOUR_USER_NAME/encodinghelper.git instead of the https version above. However, this latter version only works if you have installed an SSH key in your Bitbucket account. Doing so can make some Bitbucket operations simpler, but it's not required.)

You should now have a directory called EncodingHelper, containing only a subdirectory called .git. A word of caution: it's critical that you not change anything inside the .git directory. It can be really informative to poke around in it and see what's there (it gets more interesting once you've got some files in your repository), but if you want to change anything about your repository, you need to do so using your Git client. Mucking around with the inner workings and metadata of your VCS is a major cause of headaches, heartbreak, data loss, hives, and so on.

IntelliJ is already installed on the CMC lab machines. Before you can use it, though, it needs to be set up on your account. This is really easy, and Mike wrote up a wonderful set of instructions to follow.

If you prefer to work on your own computer, download the IntelliJ Ultimate Edition. We've got a license for anyone at Carleton to use it. When you first start it up, you'll be asked for your registration key; this is documented in a post on Piazza. (Once it's up, hopefully I'll remember to edit this paragraph and add a link. If I haven't yet, please post on Piazza and ask me to do so!)

Here are the steps. (There's also good help at the JetBrains IntelliJ Help page.)

1. Choose “Create New Project”.
2. Project SDK: if the dropdown shows “None”, click on “New...” and find the JDK installed on your system. (On some systems, IntelliJ will automatically select the right location, and you can just hit “OK”. If that doesn't happen for you, you may have to dig a bit to find the JDK that's installed on your computer. Google around, or check the JetBrains help. If you've never installed the Java compiler and dev tools on your computer before, you may have to do that first.)
3. Click “Next”.
4. Check “Create project from template” and select “Command Line App”.
5. Name the project “EncodingHelper“ and set its directory to be the EncodingHelper directory that your git clone created previously. Make sure it's not a directory inside that one! (You can also just put the project in a temporary location for now, and in the next step move it over. But creating the project directly in the repository folder worked for me.)
6. Change the “Base package” to something suitable — I used edu.carleton.jadrian.

Open up the Preferences dialog in IntelliJ. (On a Mac, it's under the main IntelliJ application menu, in the upper left.) Then open up the Editor→Code Style pane. Set these three preferences:

• Right Margin: 80
• Line Separator: Unix
• Keep indents on existing lines (make sure the box is checked)

Apply your changes. By default, IntelliJ is configured to insert spaces instead of tabs, and uses a four-space tab width. This is the correct configuration; test your editor to make sure it's right.

1. Take a look at the contents of the project you just created. You should see subfolders called .idea and src, plus a file called EncodingHelper.iml (in addition to your .git directory from before).
2. If you put your project in a temporary location before, quit out of IntelliJ and move .idea, src, and EncodingHelper.iml into your EncodingHelper Git repository.
3. On the command line, make sure you're in the EncodingHelper directory, and that you can see the .git directory inside it. Now add the new items to the repository:

   git add .idea src EncodingHelper.iml

4. Commit your changes. That is, you tell Git to make your changes a permanent part of the history of your repository. When you perform the commit operation...

   git commit

   ... you will be required to type a commit message. In this case, your message should be something like “Added the initial IntelliJ project files to the repository.”

5. Push your changes from your copy of the repository up to the Bitbucket server's copy:

   git push

6. Now load up your repository on the Bitbucket website, and make sure that the project file and src directory are there. If you've got an old version of Git (or something else weird is happening), there's a chance that your files won't show up on Bitbucket; this means that the push didn't work correctly. You may have gotten a message when you tried to push saying Everything up-to-date. In that case, try instead executing git push origin master. That's explicitly saying: “Hey git, push the code that's on my local master branch (the default one) back to the origin server.“

1. If you quit out of it before, launch IntelliJ again.
2. Open the project found in your EncodingHelper Git repository (File→Open, then select the EncodingHelper folder, then click Choose).

3. In the left-side panel, find “Main” under your src directory. Double-click on Main to see the contents of Main.java.
4. Add something like System.out.println("hello, world!"); to your main method. (Note that the indentation is incorrect in the starter code — the commented line is indented by a tab character, not four spaces. Make sure to delete the whole line and indent your code properly!)
5. Find the bug icon in the toolbar at the top of IntelliJ, and click on it.
6. Your program should compile and run. Where does the output appear?
7. Once you're happy with your hello world message or whatever Java code you have added to Main, save the file, then do git commit -a and git push. (The -a flag on the commit means “hey Git, before you commit, add all my recent changes to the commit list”. Without it, you have to issue an explicit git add for all your changed files before committing.)
8. If you feel like entertaining the graders, go nuts — this is just a Java program, and you can do whatever you want with it. But make sure that your project loads, builds, and runs by the time the assignment is due.