Skip to end of metadata
Go to start of metadata

What this tutorual is about

PyCharm supports major version control systems. However, regardless of your specific version control system, the general approach is always the same -make PyCharm functionality as VCS-agnostic as possible.

This tutorial aims to walk you step-by-step through the main versioning actions.

What this tutorial is not about

  • Basic information about the principles of version control in PyCharm are out of scope of this tutorial. This information can be found in the product documentation. Refer also to descriptions of common and VCS-related procedures.
  • Descriptions of specific version control systems are also out of scope of this tutorial. Refer to the product documentation instead.

Before you start

Make sure that:

  • You are working with PyCharm version 2.7 or higher.
  • You have a project already created. You can use the project from the Getting Started tutorial.
  • You have your VCS properly installed and configured; you have access rights to the remote repositories.

Version control commands available when VCS is not enabled

When you start working on a project in PyCharm, version control is disabled. However, there is the main menu item VCS that contains certain commands:

As you see, PyCharm makes it possible to use local history, browse the external repositories, check out sources from them, etc. You can even enable version control from this menu! The only restriction is that using this command confines your version control to the project root. If you want to make your configuration more specific, use the Settings dialog, which will be discussed in the next section.

Enabling version control

Click , and in the Settings dialog, click Version Control. By default, the only root is <project>, and it is not mapped to any version control system. Let's do it.

  • First, click . In the Add VCS Directory Mapping dialog, click the ellipsis button, and choose the directory you want to put under version control. From the VCS drop-down list, select a version control system you are going to use (in our example, let it be Git):

By the way, if you have several directories, you can map each of them to its own version control system, or leave some of them unversioned.

  • Next, apply your new version control settings, and close the Settings dialog.

How does it affect PyCharm's appearance?

Something has changed. PyCharm now looks differently...Let's explore the changes in PyCharm's UI.

  • You see the new color code of the file Now it is brown, which means that the file exists, but is not yet added to the version control.
  • Changes tool window appears - you see its button along the lower border of PyCharm. Click this button to open the tool window, and see the list of unversioned files. Later we'll see what to do with them.
  • The VCS menu, and the VCS operations pop-up now show more commands. In particular, you see the commands that allow checking your changes in the repository, and updating the entire project. These commands are denoted with the icons and respectively.
  • Same icons appear on the main toolbar.
  • A Git node appeared on the VCS menu, and on the context menus of the Project tool window and the editor. Have we selected a different version control system to associate with a directory, this node would be different (Perforce, CVS, etc.). This node contains VCS-specific commands.
  • In the Status bar, you see the Git widget - this is a Git-specific modification.

Putting a file under version control

Look at the list of unversioned files in the Changes tool window:

Select, and press Ctrl+Alt+A to add this file to version control: you see that the color code of the file changed - now it is green, which means that the file is added to version control, but not yet committed to the repository. The file moved to the new changelist with the name Default. Now press Ctrl+K (or click button in the Changes tool window) to commit your changes:

Next, enter your check-in comment, and finally click the Commit button:

OK, the changes are checked in. The Default changelist is now empty, and the color code of the file name changed again - it became black, which means that there are no pending changes.

Files under .idea directory

There are more unversioned files left. If you click the button in the Changes tool window, you will see that all these files reside in the directory .idea under the project root. However, we don't see this directory under the project root in the Project tool window.

The files under this directory are the settings files of your project. It is recommended to place all of them, except one, under version control. So, do it as described in the previous section.

Ignoring files

This only file that should be ignored, stores your workspace preferences; its name is workspace.xml. The file workspace.xml is ignored by default. Open the Ignored Files page of the Settings dialog (Version Control→Ignored Files), and see the list of files ignored by version control by default:

If you want more files to be ignored by your version control system, click , and then enter specific file name, or a mask, or a directory name. Refer to the page Configuring Ignored Files for details.

Viewing changes in the editor

Let's edit the source code: for example, rename a variable, remove a line, add a line. All the changes are marked in the left gutter:

Click a line with a change - a pop-up window with a toolbar appears:

As you see, this toolbar helps doing many useful things: navigate between changes, view differences, roll the changes back, and put the previous version to clipboard.

Refer to the page Using Change Markers to View and Navigate Through Changes in the Editor for details.

By the way, the color code of the file name changed again - it became blue, which means that there are pending changes not yet committed to your repository. Since you already know how to commit changes, do it now - and see that the change markers in the left gutter vanished.

Getting up-to-date information from the repository

Suppose somebody else is working on the same project. Now you want to get the external changes locally. PyCharm, as usual, provides several ways to do it:

  • Press Ctrl+T
  • Click on the main toolbar
  • Choose VCS→Update Project...

The action per se is VCS-agnostic. However, the dialog box that shows up when you invoke updating, is VCS-dependent. It will be different, for example, for Git update and for Perforce update - compare the dialog descriptions.


Congrats! You have successully passed this tutorial. You have performed the actions that do not depend on the specific VCS: enabled version control, put files under version control, ignored files, checked edit results in, and updated your source code.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.