Check out our NEW end-to-end Java DevOps demo video on YouTube!

ON THIS PAGE we will show you how to clone your Visual Studio Team Services Git repository and create pull requests all from within IntelliJ IDEA.
ASSUMPTIONS

  • You have read the Create Git Repo Page and performed the steps on that page to create a Team Services project and Git repository for the DeepSpace sample code.
  • You have IntelliJ IDEA installed on your machine (if not, get IntelliJ IDEA).

IntelliJ

IntelliJ IDEA is an IDE produced by JetBrains. You can find out more about it at https://www.jetbrains.com/idea/. The Visual Studio Team Services Plugin for IntelliJ allows you to connect to your Git repositories on Team Services and Team Foundation Server (TFS) in a seamless and intuitive way. You can also use this plugin to import projects into Team Services or create pull requests in your Team Services/TFS Git repository.

Installing the Team Services Plugin for IntelliJ

See the IntelliJ Plugin download page for instructions on downloading and installing the plugin.

The plugin is compatible with IntelliJ IDEA Ultimate and Community editions, Android Studio, RubyMine, WebStorm, PhpStorm, PyCharm, AppCode, MPS, 0xDBE and CLion.*

Cloning your repo in IntelliJ

To clone your Team Services repo in IntelliJ is extremely simple. You don't even need to know the URL for the repo. Simply open IntelliJ IDEA and select Check out from Version Control and then choose "Team Foundation Git".

Next just sign in to Team Services...

When you click "Sign in", you will be presented with the standard Team Services sign in UI. Once signed in, you should see the list of all repositories you have access to on Team Services. Simply choose the correct repo, DeepSpace, and click the Clone button. (You may also want to choose where on your hard drive the repo is cloned to by changing the Parent Directory.)

After the clone finishes, IntelliJ will ask you if you want to open the project. Click "Yes" and you should end up with the DeepSpace project opened in IntelliJ IDEA.

Making some changes in IntelliJ

Start by making sure the project builds using Build->Make project. If you are prompted to add an SDK for the project, simply add the latest Java JDK installed on your machine. If you want to run the project now to see what it does, you can do the following:

  • from the DeepSpace root folder in your git repo, run the command "mvn jetty:run" (this requires maven to be installed)
  • from a browser, go to http://localhost:3030/ You should see stars and planets flying by! If you look closely, you may notice that Earth does not fly by.

In our DeepSpace example, there are some code sections that have been commented out. If you open the src/main/java/com.microsoft.tfs.demo/ImageService.java file in IntelliJ, you can see one of the sections.

Let's fix this section of code locally. Typically, when working in a Git repo, you should create a branch for your work and commit to that branch. You can create a branch through IntelliJ using the built-in VCS->Git->Branches window. When prompted, use the branch name "fixBugs".

Once we have a branch to make our changes in, we can uncomment the code and rebuild the project. If you follow the instructions above to run the program again, you should see the Earth fly by. Now that our changes are built and tested, we can commit them locally using the VCS->Commit Changes menu. In the commit dialog, you will see a Team Services button above the commit message text box. Click on that button to view your list of work items assigned to you. Select the "Add Missing Earth" work item and click OK. You will see the commit message text box populate with the work item's type, number, and title. This will associate the work item to this commit for traceability in the future.

This change is only done locally; it hasn't been changed in our Team Services repo yet.

Creating a Pull Request

You can push your local branch to the server and create a pull request for your team to review. Our plugin helps you create the pull request based on your current context within IntelliJ. This saves you several steps and eliminates the need for you to switch to your browser to create the pull request.

To accomplish this, simply select VCS->Git->Create Pull Request. This will open up the "Create Pull Request" dialog. This dialog provides a lot of information including the files that have changed and the commits that will be pushed. You can give the pull request a title and a description.

After you click "Create Pull Request", you should receive a notification that the pull request was created. It also contains a link to the pull request in case you want to add specific reviewers or comments. Once the code reviews are done, you can merge the pull request into master.

Checking Build Status

After you have merged your changes into master, you can check if your CI build has succeeded from within IntelliJ. In the bottom right corner, there is an icon that displays your build status to you. If you see a green checkmark, that means your build has succeeded. If you see a red X, then your build failed. If you see a gray question mark, your build was not found or your credentials may have expired.

You can click on the icon for more options such as viewing build details, queuing a new build, and updating the status manually.

View Pull Requests and Work Items

Under the Version Control menu, a Pull Request tab and Work Items tab exist to allow you to easily view the information you need without leaving the IDE. The Pull Request tab shows you the current pull requests created by you and assigned to you along with their status. The tab also gives you the ability to create and/or abandon pull requests.

Under the Work Items tab, you can view the work items based on queries that you have created or use the default query to see work items that are assigned to you. You can also create a branch based off of a work item so that you can associate a work item with branch for future traceability purposes.

TFVC Support

TFVC support is also available in the plugin. The current features supported are:

  • Checkout a TFVC repository from Team Services or Team Foundation Server 2015+.
  • Execute all basic version control actions such as add, delete, rename, move, etc.
  • View local changes, server changes, and history for your files.
  • Create, manage, and edit your workspaces.
  • Checkin and update local files.
  • Merge conflicts from updates.
  • Create and merge branches.
  • Create labels.
  • Lock and unlock files and directories.
  • Associate work items with checkins.
  • Supports using a TFS proxy.
  • Local workspace support only.

The TFVC functionality is available from the VCS dropdown menu in the toolbar or from right clicking in the Project window. A TFVC menu item will display the options available for you to use. A demo of the TFVC features can be found here.

TFVC Setup Requirements

You must have the TF command line tool installed to be able to use TFVC features. The minimum version supported by the plugin is 14.0.3. To install the tool, download the latest "TEE-CLC-14.*.*.zip" file and extract it to a known location. After extracting the files, you must accept the license agreement. To do so, open a Command Prompt/Terminal window, navigate to the extracted directory, and run tf eula. After reading the EULA, enter y to accept it. NOTE: If you forget to do this, the plugin may fail to load with a RuntimeException.

For the tool to be detected by the plugin, you must set the location of the executable in the Settings/Preferences menu by following these instructions:

  1. Go to File then Settings in the toolbar for Windows and Linux. For Mac, go to Android Studio then Preferences.
  2. Choose Version Control from the left menu then TFVC.
  3. In the Path to tf executable text field, navigate to the location of the tf executable.
  4. Click Test to test that the executable has been found and is working as expected.
  5. Click Apply then OK to save and exit.

If you intend to use the tf tools from the command line, you may want to add this folder to your PATH environment variable as well.

If you do not want to get prompted to enter your credentials for each tf command that you run, set the TF_AUTO_SAVE_CREDENTIALS environment variable to 1.

Setting TFVC as the Version Control System

If TFVC does not come up as your version control system (VCS) then it can be set manually. Go to the VCS dropdown menu in the toolbar and select Enable Version Control Integration. Select TFVC from the dropdown menu and click OK.

Using existing workspaces created by Visual Studio

Initially, IntelliJ cannot detect workspaces created by Visual Studio. To get a workspace to be recognized, you must use the TF Command Line tool. Run tf workspaces -collection:<collection-url> where the collection URL is the one associated with the workspace you are using.

Next Steps

Watch our end-to-end tutorial on how to incorporate the various plugin features into your development routine to make working with Team Services even easier.

Frequently Asked Questions (FAQ)

Q: Where can I learn more about installing the IntelliJ plugin?

A: Watch a how-to video on installing the plugin on our YouTube channel.

Q: How can I import my IntelliJ project into Visual Studio Team Services?

A: Watch a how-to video on importing projects on our YouTube channel.

Q: How can I checkout a Visual Studio Team Services Git repo from within IntelliJ?

A: Watch a how-to video on checking out projects on our YouTube channel.

Q: How can I create a pull request using the IntelliJ plugin?

A: Watch a how-to video on pull requests on our YouTube channel.

Q: Where can I learn more about the Team Services Pull Request feature?

A: This Conduct a Git pull request article provides more details.

Q: What if I can't see any repositories after signing in?

A: In some rare cases, the list of repositories is empty after signing in with your Visual Studio Team Services account. If that happens, you can click the Team Foundation Server tab and enter the URL to your Team Services account in the Server URL textbox and then click Connect. If you don't know the URL to your Team Services account, the Team Services accounts you have access to will be listed at https://app.vssps.visualstudio.com.

Q: When I test the tf executable, I get a warning that the version detected is 0.0.0. How can I make it detect the actual version?

A: This has been seen in version 14.0.3 and below of the TF Comand Line Tool when it defaults to not use English for the output. This has been fixed in the newer versions of the tool which can be downloaded from GitHub.

Q: How do I collect logs to help troubleshoot an issue?

A: First enable logging for com.microsoft.alm, reproduce the issue and send us the idea.log file:

  1. Help->Configure Debug Log Settings...
  2. In the Custom Debug Log Configuration textbox, add the following on its own line: com.microsoft.alm
  3. Click OK
  4. Try to reproduce the issue you encountered.
  5. Help->Show Log in Finder/Explorer/File Manager
  6. The file idea.log should be highlighted. You can open it with a text editor to review its contents for sensitive information and to make sure there are entries containing microsoft.
  7. Compress the file.
  8. Create a GitHub issue and attach the file to it.