PyCharm 2019.3 Help

Review Changes

This topic explains how to keep track of the changes that you and your teammates introduce to the source code.

Review project history

PyCharm allows you to review all changes made to the project sources that match the specified filters.

For distributed version control systems, such as Git and Mercurial, you can view project history in the Log tab of the Version Control tool window Alt+9 (see Investigate changes).

For centralized version control systems, such as Subversion, Perforce, and ClearCase, project history is available in the Repository tab of the Version Control tool window Alt+9.

Track changes to a file in the editor

As you modify a file that is under version control, all changes are highlighted in the editor with change markers that appear in the gutter next to the modified lines and show the type of changes introduced since the last synchronization with the repository. When you commit the modified file to the repository, the change markers disappear.

The changes you introduce to the text are color-coded:

  • marker for a newly added line line added.

  • marker for a modified line line changed.

To customize the default colors for line statuses, in the Settings/Preferences dialog Ctrl+Alt+S, go to Editor | Color Scheme | VCS.

When you delete a line, the following marker appears in the gutter: deleted line marker.

You can manage changes using the dedicated toolbar. To invoke it, hover the mouse cursor over a change marker and then click it. The toolbar is displayed together with a frame showing the previous contents of the modified line:

change marker toolbar

The actions in the toolbar let you navigate to the next or previous change, rollback a change, view the differences between the current and the repository version, copy the previous version of the modified line to Clipboard, or turn on highlighting differences in the code.

If you want to turn off highlighting changes, in the Settings/Preferences dialog Ctrl+Alt+S select Editor | General on the left, and uncheck the Highlight modified lines in gutter option.

Compare local changes with the repository version

Apart from navigating through your local changes within a file in the editor, you can review these changes compared to the base revision of the file.

You can review changes in one of the following ways:

  • Preview changes in the Local Changes tab of the Version Control tool window Alt+9: select a file and click Preview Diff preview details on the toolbar.

  • Explore changes in the Differences Viewer: select a file and press Ctrl+D or click show diff on the toolbar.

The left pane shows the affected code as it was in the base revision, and the right page shows the affected code after changes have been made.

Use the toolbar buttons and controls to navigate between changes and configure the appearance of the Change Details pane or the Differences Viewer:

Item

Tooltip and Shortcut

Description

the Previous Difference button/the Next Difference button

Previous Difference / Next Difference Shift+F7 F7

Use these buttons to jump to the next/previous difference.

When the last/first difference is reached, PyCharm suggests to click the arrow buttons F7/Shift+F7 once more and compare other files, depending on the Go to the next file after reaching last change option in the Differences Viewer settings.

This behavior is supported only when the Differences Viewer is invoked from the Version Control tool window Alt+9 .

the Edit button

Jump to Source
F4

Click this button to open the selected file in the active pane in the editor. The caret will be placed in the same position as in the Differences Viewer.

the Back button
the Forward button

Compare Previous/Next File
Alt+LeftAlt+Right

Click these buttons to compare the local copy of the previous/next file with its update from the server.

the Go To Changed File button

Go To Changed File Ctrl+N

Click this button to display all changed files in the current change set (and navigate to them). This button only appears when you are reviewing changes in multiple files (for example, in the Local Changes tab of the Version Control tool window Alt+9.

Viewer type

Use this list to choose a viewer type. The side-by-side viewer has two panels; the unified viewer has one panel only.

Both types of viewers enable you to

  • Edit code. Note that one can change text only in the right-hand part of the default viewer, or, in case of the unified viewer, in the lower ("after") line, that is in your local version of the file.

  • Perform the Apply/Append/Revert actions.

Whitespace

Use this list to define how the differences viewer should treat whitespaces.

  • Do not ignore: white spaces are important, and all differences are highlighted. This option is selected by default.

  • Trim whitespaces: ("\t", " "), if they appear in the end and in the beginning of a line.

    • If two lines differ in trailing whitespaces only, these lines are considered equal.

    • If two lines are different, such trailing whitespaces are not highlighted in the By word mode.

  • Ignore whitespaces: white spaces are not important, regardless of their location in the source code.

  • Ignore whitespaces and empty lines: the following entities are ignored:

    • all whitespaces (as in the 'Ignore whitespaces' option)

    • all added or removed lines consisting of whitespaces only

    • all changes consisting of splitting or joining lines without changes to non-whitespace parts.
      For example, changing a b c to a \n b c is not highlighted in this mode.

Highlighting mode

Select the way differences granularity is highlighted.

The available options are:

  • Highlight words: the modified words are highlighted

  • Highlight lines: the modified lines are highlighted

  • Highlight split changes: if this option is selected, big changes are split into smaller 'atomic' changes.
    For example, A \n B vs. A X \n B X will be treated as two changes instead of one.

  • Highlight symbols: the modified symbols will be highlighted

  • Do not highlight: if this option is selected, the differences are not highlighted at all. This option is intended for significantly modified files, where highlighting only introduces additional difficulties.

the Collapse All button

Collapse unchanged fragments

Click this button to collapse all unchanged fragments in both files. The amount of non-collapsible unchanged lines is configurable in the Diff & Merge settings page.

the Synchronize button

Synchronize scrolling

Click this button to simultaneously scroll both differences panes; if this button is released, each of the panes can be scrolled independently.

the Settings button

Settings

Click this button to invoke the list of available settings. Select or clear these options to show or hide whitespaces, line numbers and indent guides, to use or disable the use of soft wraps, and to set the highlighting level.

These commands are also available from the context menu of the differences viewer gutter.

the External Tools icon

Show diff in external tool

Click this button to invoke an external differences viewer, specified in the External Diff Tools settings page.

This button only appears on the toolbar when the Use external diff tool option is enabled in the External Diff Tools settings page.

the Help button

Help
F1

Click this button to show the corresponding help page.

N/A

Annotate

This option is only available from the context menu of the gutter.

Use this option to explore who introduced which changes to the repository version of the file, and when. The annotations view lets you see detailed information for each line of code, such as the version from which this line originated, the ID of the user who committed this line, and the commit date.

For more details on annotations, refer to VCS annotations

The most useful shortcuts are the following:

Shortcut

Description

Use this keyboard shortcut to show the popup menu of the most commonly used diff commands.

Ctrl+Tab

Use this keyboard shortcut to switch between the left and the right panes.

Ctrl+Shift+Tab

Use this keyboard shortcut to select the position obtained by Ctrl+Tab in the opposite pane.

Ctrl+Z/Ctrl+Shift+Z

Use this keyboard shortcut to undo/redo a merge operation. Conflicts will be kept in sync with the text.

View changes history for a file or selection

PyCharm allows you to review changes made to files or even fragments of source code. The Show History and the Show History for Selection commands are available from the main VCS menu and from the context menu of files.

The change history for a file is displayed in the dedicated History tab of the Version Control tool window Alt+9.

The change history for a selection of code is displayed in a separate window, in the form of the differences viewer.

View history for file

  • Open a file in the editor or select in the Project tool window and choose <VCS> | Show History from the context menu.

The History tab for the selected file appears in the Version Control tool window Alt+9, the name of the file is shown on the title bar of the tab.

You can use the toolbar buttons to compare the selected revision with the local version, compare classes from the selected revision, checkout the selected revision from your VCS, annotate the selected revision, and so on:

Item

Tooltip and Shortcut

Description

the Refresh button

Refresh

Click this button to refresh the current information.

the Show diff icon

Show Diff
Ctrl+D

Click this button to compare the selected revision of a file with its previous revision in the Differences Viewer.

the Show All Affected Files button

Show All Affected Files
Shift+Alt+A

Click this button to open the Paths Affected in Revision dialog where you can view all files that were modified in the selected revision.

the Show All Branches button

Show All Branches

Click this button to display changes from branches other than the current one.

the Eye icon

Presentation Settings

Click to choose the amount of information you want to see in the History view. You can also select the Show Commit Timestamp option if you want PyCharm to show the commit timestamp instead of the time when a change was authored.

the Show Details icon

Show Details

Click this button to show the commit message for the selected revision.

the Open on GitHub button

Open in GitHub

Click this button to open the page that corresponds to the selected commit on GitHub.

View history for selection

  1. In the editor, select a fragment of the source code, or position the caret at the line whose history you want to track.

  2. Choose <VCS> | Show History for Selection from the main VCS menu or from the context menu of the selection.

The history for the selected fragment will open in a separate window. If nothing is selected the history will be displayed for the current line.

Check file status

PyCharm allows you to check the status of project files relative to the repository. File status shows you which operations have been performed on the file since you last synchronized with the repository.

You can check the status of a file in any interface element (for example, the editor, or various tool windows) by the color used to highlight the filename.

You can customize the default colors for file statuses in Colors and Fonts settings page.

Color

File Status

Description

Color sample: dark green #0A7700

Added

The file in the active changelist is scheduled for addition to the repository.

Color sample: green #0EAA00

Added in not active changelist

The file in an inactive changelist is scheduled for addition to the repository. This file status is available if the Highlight files from non-active changelists option is enabled in Settings/Preferences | Version Control | Changelists.

Color sample: red #FF0000

Changelist conflict

The file in an inactive changelist has been modified in the active changelist. In this case, a new dialog will open prompting you to resolve the changelist conflict. This file status is available if all options are enabled in Settings/Preferences | Version Control | Changelists.

Color sample: dark green #0A7700

Copied

If a file is a copy of another file, its metadata is tracked, and such a file is marked as copied.

Color sample: grey #616161

Deleted

The file is scheduled for deletion from the repository.

Color sample: dull purple #773895

Deleted from file system

The file has been deleted locally, but hasn't been scheduled for deletion, and it still exists in the repository.

Color sample: light grayish blue #8AA4C8

Have changed descendants

If a file is modified, the IDE will recursively highlight all directories containing that file. This status is available if the Show directories with changed descendants option is enabled in Settings/Preferences | Version Control.

Color sample: bright blue #3264B4

Have immediate changed children

If a file is modified, the IDE will highlight its parent directory. This status is available if the Show directories with changed descendants option is enabled in Settings/Preferences | Version Control.

Color sample: light brown #B28C00

Hijacked

[Perforce, ClearCase, VSS] The file is modified without checkout.

Color sample: dark olive #727238

Ignored

A file is intentionally untracked by VCS.

Color sample: purple #7503DC

Merged

The file is merged by your VCS as a result of an update.

Color sample: red #FF0000

Merged with conflicts

During the last update, the file has been merged with conflicts.

Color sample: red #FF0000

Merged with property conflicts

During the last update, the IDE has detected differences between the properties of the local file and its server version.

Color sample: red #FF0000

Merged with text and property conflicts

Text and property conflicts happen when two or more developers modify the same lines of a file and the same file properties.

Color sample: bright navy #0032A0

Modified

The file has changed since the last synchronization.

Color sample: blue #0047E4

Modified in not active changelist

The file in an inactive changelist has been modified. This file status is available if the Highlight files from non-active changelists option is enabled in Settings/Preferences | Version Control | Changelists.

Color sample: Olive #7C7C00

Obsolete

The file should no longer be in your working copy of the repository.

Color sample: teal #007C7C

Renamed

Since the last update, the file has been renamed.

Color sample: dark cyan #08978F

Switched

[SVN] The file is taken from a different branch than the whole project.

Color sample: brown #993300

(Unknown) Unversioned

The file exists locally, but is not in the repository, and is not scheduled for addition.

Color sample: black None (default color)

Up to date

The file hasn't been changed.

Color

File Status

Description

Color sample: dull green #629755

Added

The file in the active changelist is scheduled for addition to the repository.

Color sample: dull green #629755

Added in not active changelist

The file in an inactive changelist is scheduled for addition to the repository. This file status is available if the Highlight files from non-active changelists option is enabled in Settings/Preferences | Version Control | Changelists.

Color sample: dull red #D5756C

Changelist conflict

The file in an inactive changelist has been modified in the active changelist. In this case, a new dialog will open prompting you to resolve the changelist conflict. This file status is available if all options are enabled in Settings/Preferences | Version Control | Changelists.

Color sample: green #0A7700

Copied

If a file is a copy of another file, its metadata is tracked, and such a file is marked as copied.

Color sample: grey #6C6C6C

Deleted

The file is scheduled for deletion from the repository.

Color sample: dull purple #6C6C6C

Deleted from file system

The file has been deleted locally, but hasn't been scheduled for deletion, and it still exists in the repository.

Color sample: light blue #6897BB

Have changed descendants

If a file is modified, the IDE will recursively highlight all directories containing that file. This status is available if the Show directories with changed descendants option is enabled in Settings/Preferences | Version Control.

Color sample: light blue #6897BB

Have immediate changed children

If a file is modified, the IDE will highlight its parent directory. This status is available if the Show directories with changed descendants option is enabled in Settings/Preferences | Version Control.

Color sample: white None (default color)

Hijacked

[Perforce, ClearCase, VSS] The file is modified without checkout.

Color sample: light olive #848504

Ignored

A file is intentionally untracked by VCS.

Color sample: light purple #9876AA

Merged

The file is merged by your VCS as a result of an update.

Color sample: dull red #D5756C

Merged with conflicts

During the last update, the file has been merged with conflicts.

Color sample: dull red #D5756C

Merged with property conflicts

During the last update, the IDE has detected differences between the properties of the local file and its server version.

Color sample: dull red #D5756C

Merged with text and property conflicts

Text and property conflicts happen when two or more developers modify the same lines of a file and the same file properties.

Color sample: light blue #6897BB

Modified

The file has changed since the last synchronization.

Color sample: light blue #6897BB

Modified in not active changelist

The file in an inactive changelist has been modified. This file status is available if the Highlight files from non-active changelists option is enabled in Settings/Preferences | Version Control | Changelists.

Color sample: white None (default color)

Obsolete

The file should no longer be in your working copy of the repository.

Color sample: strong cyan #3A8484

Renamed

Since the last update, the file has been renamed.

Color sample: white None (default color)

Switched

[SVN] The file is taken from a different branch than the whole project.

Color sample: soft red #D1675A

(Unknown) Unversioned

The file exists locally, but is not in the repository, and is not scheduled for addition.

Color sample: white None (default color)

Up to date

The file hasn't been changed.

Color

File Status

Description

Color sample: green #62CC47

Added

The file in the active changelist is scheduled for addition to the repository.

Color sample: green #62CC47

Added in not active changelist

The file in an inactive changelist is scheduled for addition to the repository. This file status is available if the Highlight files from non-active changelists option is enabled in Settings/Preferences | Version Control | Changelists.

Color sample: dull red #FF6666

Changelist conflict

The file in an inactive changelist has been modified in the active changelist. In this case, a new dialog will open prompting you to resolve the changelist conflict. This file status is available if all options are enabled in Settings/Preferences | Version Control | Changelists.

Color sample: green #62CC47

Copied

If a file is a copy of another file, its metadata is tracked, and such a file is marked as copied.

Color sample: orange #ED864A

Deleted

The file is scheduled for deletion from the repository.

Color sample: orange #ED864A

Deleted from file system

The file has been deleted locally, but hasn't been scheduled for deletion, and it still exists in the repository.

Color sample: vivid cyan #4FF0FF

Have changed descendants

If a file is modified, the IDE will recursively highlight all directories containing that file. This status is available if the Show directories with changed descendants option is enabled in Settings/Preferences | Version Control.

Color sample: vivid cyan #4FF0FF

Have immediate changed children

If a file is modified, the IDE will highlight its parent directory. This status is available if the Show directories with changed descendants option is enabled in Settings/Preferences | Version Control.

Color sample: white None (default color)

Hijacked

[Perforce, ClearCase, VSS] The file is modified without checkout.

Color sample: light olive #A9B837

Ignored

A file is intentionally untracked by VCS.

Color sample: light purple #ED94FF

Merged

The file is merged by your VCS as a result of an update.

Color sample: dull red #FF6666

Merged with conflicts

During the last update, the file has been merged with conflicts.

Color sample: dull red #FF6666

Merged with property conflicts

During the last update, the IDE has detected differences between the properties of the local file and its server version.

Color sample: dull red #FF6666

Merged with text and property conflicts

Text and property conflicts happen when two or more developers modify the same lines of a file and the same file properties.

Color sample: vivid cyan #4FF0FF

Modified

The file has changed since the last synchronization.

Color sample: vivid cyan #4FF0FF

Modified in not active changelist

The file in an inactive changelist has been modified. This file status is available if the Highlight files from non-active changelists option is enabled in Settings/Preferences | Version Control | Changelists.

Color sample: white None (default color)

Obsolete

The file should no longer be in your working copy of the repository.

Color sample: vivid cyan #4FF0FF

Renamed

Since the last update, the file has been renamed.

Color sample: white None (default color)

Switched

[SVN] The file is taken from a different branch than the whole project.

Color sample: soft red D1675A

(Unknown) Unversioned

The file exists locally, but is not in the repository, and is not scheduled for addition.

Color sample: white None (default color)

Up to date

The file hasn't been changed.

VCS annotations

What are VCS annotations?

Annotation is a form of file presentation that shows detailed information for each line of code. In particular, for each line you can see the version from which this line originated, the user ID of the person who committed this line, and the commit date. The annotated view helps you find out who did what and when, and trace back the changes.

Annotating lines of code is available for ClearCase, Mercurial, Git, Perforce and Subversion.

The Annotate command is available from VCS-specific nodes of the Version Control menu, the context menu of the Editor gutter, file context menus, and the file history view.

When annotations are enabled, the gutter looks similar to the following example:

annotate

Annotations for lines modified in the current revision, are marked with bold type and an asterisk.

Enable annotations

  • Right-click the gutter in the editor or in the Differences Viewer and select Annotate from the context menu.

    You can assign a custom shortcut to the Annotate command: in the Settings/Preferences dialog Ctrl+Alt+S choose Keymap on the left and go to Version Control | Git | Annotate.

Configure the amount of information shown in annotations

You can choose how much information you want to see in the annotations view.

  • Right-click the annotations gutter, choose View and select which type of information you want to see, including the revision from which this change originated, the date, the name of the author in different formats, and the commit number.

    You can also set highlighting under Colors.

Configure annotation options

  • Right-click the annotations gutter and select Options from the context menu:

    • Ignore Whitespaces: whitespaces will be ignored (git blame -w). This means that annotations will point to the previous meaningful commit.

    • Detect Movements Within File: when a commit moves or copies lines within the same file, such change will be ignored (git blame -M). This means that annotations will point to the previous meaningful commit.

    • Detect Movements Across Files: when a commit moves or copies lines from other files that were modified in the same commit, such change will be ignored (git blame -C). This means that annotations will point to the previous meaningful commit.

    • Show Commit Timestamp: select this option if you want PyCharm to show the commit timestamp in the Annotations view instead of the time when a change was authored.

Customize date format

  1. In the Settings/Preferences dialog Ctrl+Alt+S go to Appearance & Behavior | System Settings | Date Formats.

  2. Click the Date Time Pattern field next to VCS Annotate and specify the date format that you want to use for VCS annotations. See patterns reference.

Annotate previous revisions

PyCharm lets you annotate not only the current file revision, but also it's previous revisions. The following options are available from the context menu of the annotations gutter:

  • Annotate Revision: this option is useful if you want to check what a file looked like after a particular change was committed. To do this, right-click this change and select Annotate Revision from the context menu.

  • Annotate Previous Revision: this option is useful if you find yourself in a situation when the last change in a particular line is meaningless, for example if all that was changed is code formatting. In this case, you can check what the previous revision of the file looked like. To do this, right-click a change and select Annotate Previous Revision from the context menu.

You can also annotate a particular file from the file history view. In the History tab, select the file version you want to review, right-click the corresponding line and select Annotate from the context menu.

View the differences between revisions

To review the differences between the annotated version of a file and its previous version, position the caret at the annotation, right-click it and select Show Diff from the context menu. PyCharm opens the Differences viewer for files:

differences viewer

You can also call the VCS Operations Popup Alt+` and select Annotated Line | Show Diff.

Navigate to log

If you are using Git for version control, you can also jump from the annotations view to the corresponding commit in the Log tab of the Version Control tool window Alt+9.

To do this, position the caret at the annotation, right-click it and select Select in Git log from the context menu. You can also use the Copy revision number command to located a revision in the log.

For projects hosted on https://github.com/, the Open on GitHub command is also available that takes you to the corresponding commit.

Last modified: 2 April 2020