A starters guide to using the Version Control System (VCS) in Intellij IDEA

intellij_vcs_guide.md

Cloning a repository from GitHub locally

First open Intellij's starting window and find the Checkout from Version Control drop-down menu:

If this is your first time doing anything like this, you'll more than likely be asked to provide your GitHub account username and password to gain access to the GitHub VCS features.

If you have 2-Factor-Authentication enabled on your GitHub account, you'll also have to provide the 6 digit authenticator every time you clone a new repository.

With that, you'll be greeted by a menu with three fields.

1. The GitHub repository URL you wish to clone
   • You'll need write permissions if you want to push commits to the repo from Intellij.
2. The parent directory you wish create a project directory where you will clone the repo into.
   • This is NOT the name of the project directory! This is the name of the directory that the project folder will be created in! So say you want to clone a repo called foo into the directory /home/you/documents/foo you'd want to specify this field as: /home/you/documents, and not /home/you/documents/foo!
3. The name of the project directory that will be created inside of the one specified in 2.
   • For the example repo detailed in 2 you would field this as foo so the repo would be cloned into /home/you/documents/foo.

The .ignore Plugin

Before we continue, you are also going to want to grab the free .ignore plugin, as it's excellent for visually understanding and handling how git and .gitignore files affects your project.

This is typically packaged with Intellij IDEA Ultimate, and possibly with Intellij IDEA Community, but you should check just to be sure.

For those generally new to versioning in general, a good repository should always have proper .gitignore to prevent leaking unreleased features or sensitive, private, files, committing IDE or project specific files (the example in Working With The VCS Tab has a couple of these directories such as .idea and .gradle, which are highlighed orange to signify this characteristic), or to prevent certain files from causing VCS issues.

Still unsure? Check out the Git Documentation as it provides a brief overview of what exactly it does.

Working with the VCS Tab

I will be using some terms to refer to certain features and/or places in the Intellij editor window, so lets go over those:

• VCS Tab refers to the tab at the top of the window labled "VCS"
• Git Tab (or GitHub Tab) refers to the child-tab in the VCS Tab labled "Git"
• Project View refers to the tool window called Project
• Version Control Panel (or VC Panel) refers to the tool window called Version Control

Also some terms that I will be using that refer to certain aspects or ideas:

• Remote refers to the GitHub repository.
  • A "Remote Branch" for example, refers to the GitHub version of the "Branch".
• Local refers to your computer's repository.
  • A set of "Local Changes" are the changes on your computer that haven't been pushed to the GitHub repository.

And finally, actions that I will refer to commonly:

• Changes is a set of one or more code modifications that are not "official" yet.
  • These changes haven't been committed locally or remotely.
• Committing is the process of serializing changes either locally or remotely.
  • Note that local changes are not necessarily committed remotely, and visa-versa.
• Pushing is the act of serializing a set of changes from the local to the remote.
  • For the context of working with Intellij, it will only be used when referring to local -> remote.
• Pulling is the act of serializing a set of changes from one branch (remote or local) to another branch (also remote or local).
  • Unlike pushing, this can be used to update the local based on changes made to the remote.
  • However, this is also a term used to describe a remote update based on another remote