Set up a Git repository
Check out a project from a remote host (clone)
PyCharm allows you to check out (in Git terms clone) an existing repository and create a new project based on the data you've downloaded.
- From the main menu, choose VCS | Checkout from Version Control | Git, or, if no project is currently opened, choose Checkout from Version Control | Git on the Welcome screen (select the GitHub option for projects hosted on https://github.com/.
- In the Clone Repository dialog, specify the URL of the remote repository you want to clone (you can click Test to make sure that connection to the remote can be established).
- In the Parent Directory field, specify the path where the folder for your local Git repository will be created.
- In the Directory Name field, specify the name of the folder into which the repository will be cloned.
- Click Clone. If you want to create a PyCharm project based on the sources you have cloned, click Yes in the confirmation dialog. Git root mapping will be automatically set to the project root directory.
Put an existing project under Git version control
Apart from cloning a remote repository, you can create a local repository based on an existing project's sources.
To import an entire project into a single Git repository that will reside in the project root, do the following:
- Open the project that you want to put under Git.
- From the main menu, choose VCS | Enable Version Control Integration.
- In the dialog that opens, select Git from the drop-down list and click OK.
If your project contains several modules that you want to put into different Git repositories, do the following:
- Open the project that you want to put under Git.
- From the main menu, choose VCS | Import into Version Control | Create Git Repository.
- In the dialog that opens, specify the directory where a new Git repository will be created.
Add files to the local repository
After you have initialized a Git repository for your project, you need to add project data to it.
- Open the Version Control tool window (Alt+9) and switch to the Local Changes tab.
- Put any files in the Unversioned Files changelist under version control by pressing Ctrl+Alt+A or selecting Add to VCS from the context menu. You can either add the entire changelist, or select separate files.
If you have enabled Git integration for your project, PyCharm suggests to add each newly created file under Git version control (you can change this behavior in the Settings dialog (Ctrl+Alt+S) under Version Control | Confirmation). If you want certain files to always remain unversioned, you can configure Git to ignore them.
Exclude files from version control (ignore)
Sometimes you may need to leave files of certain types unversioned. These can be VCS administration files, artifacts of utilities, backup copies, etc.
You can ignore files through PyCharm, and the IDE will not suggest adding them to Git and will highlight them as ignored. However, since this is done on the IDE side, Git treats such files as unversioned, so if you need to perform any operations outside PyCharm, or share your project, it is also recommended to add a list of files you want to ignore to the
gitignore file (for instructions, see https://git-scm.com/docs/gitignore).
To configure a list of files that you don't want to be tracked by Git in PyCharm, do the following:
- Choose File | Settings from the main menu, and select Version Control | Ignored Files in the left pane.
- Open the Version Control tool window (Alt+9) and switch to the Local Changes tab. Click the Configure Ignored Files icon on the toolbar.
- Click the Add button on the toolbar.
- In the Ignore Unversioned Files dialog, specify the files/directories that you want to ignore, or define file name patterns:
- Ignore specified file: specify the file name relative to the project root.
- Ignore all files under: specify the directory whose contents should be ignored relative to the project root. The rule is applied recursively to all subdirectories.
- Ignore all files matching: type the pattern that defines the names of files to be ignored. The rule is applied to all directories under the project root.
Two characters can be used as wildcards:
*: to replace any string.
?: to replace a single character.
*.imlwill ignore all files with the
*.?mlwill ignore all files whose extension ends with
Check project status
PyCharm allows you to check the status of your local working copy compared to the repository version of the project. It lets you see which files have been modified, which new files have been added to the VCS, and which files are not being tracked by Git.
Open the Version Control tool window (Alt+9) and switch to the Local Changes tab:
- The Default changelist shows all files that have been modified since you last synchronized with the remote repository (highlighted in blue), and all new files that have been added to the VCS but have not been committed yet (highlighted in green).
- The Unversioned Files changelist shows all files that have been added to your project, but that are not being tracked by Git.
For more info on changelists, see Group changes into different changelists.
Track changes to a file in the editor
You can also track changes to a file as you modify it in the editor. All changes are highlighted with change markers that appear in the left gutter next to the modified lines, and show the type of changes introduced since you last synchronized with the repository. When you commit changes to the repository, change markers disappear.
The changes you introduce to the text are color-coded:
- line added.
- line changed.
When you delete a line, the following marker appears in the left gutter: .
You can manage changes using a toolbar that appears when you 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:
You can rollback changes by clicking (note that all changes to the file since its last revision will be reverted, not just the current line), and explore the differences between the current and the repository version of the current line by clicking .
Add a remote repository
If you have cloned a remote Git repository, for example from GitHub, the remote is configured automatically and you do not have to specify it when you want to synchronize with it (i.e. when you perform a pull or a push operation).
However, if you created a Git repository based on local sources, you need to add a remote repository for other contributors to be able to push their changes to it, and for you to be able to share the results of your work.
- Invoke the Push dialog when you are ready to push your commits by selecting VCS | Git | Push from the main menu, or press Ctrl+Shift+K.
- In the dialog that opens, specify the remote name and the URL where it will be hosted, and click OK.
In some cases, you also need to add a second remote repository. This may be useful, for example, if you have cloned a repository that you do not have write access to, and you are going to push changes to your own fork of the original project. Another common scenario is that you have cloned your own repository that is somebody else's project fork, and you need to synchronize with the original project and fetch changes from it. In this case:
- From the main menu, choose VCS | Git | Remotes. The Git Remotes dialog will open.
- Click the Add button on the toolbar or press Alt+Insert.
- In the dialog that opens, specify the remote name and URL and click OK.
Learn more from this video:
To edit a remote (for example, to change the name of the original project that you have cloned), select it in the Git Remotes dialog and click the Edit button on the toolbar, or press Enter.
To remove a repository that is no longer valid, select it in the Git Remotes dialog and click the Remove button on the toolbar, or press Alt+Delete.