WebStorm 2017.3 Help

Using Git integration

Check out an existing project from a remote host

WebStorm allows you to check out (in Git terms clone) an existing repository and create a new project based on the data you've downloaded.

  1. 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.
  2. 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).
  3. In the Parent Directory field, specify the path where the folder for your local Git repository will be created.
  4. In the Directory Name field, specify the name of the folder into which the repository will be cloned.
  5. Click Clone. If you want to create a WebStorm 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:

  1. Open the project that you want to put under Git.
  2. From the main menu, choose VCS | Enable Git Integration.
  3. 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:

  1. Open the project that you want to put under Git.
  2. From the main menu, choose VCS | Import into Version Control | Create Git Repository.
  3. 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.

  1. Open the Version Control tool window (Alt+9) and switch to the Local Changes tab.
  2. 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, WebStorm 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

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 WebStorm, 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 WebStorm, 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 WebStorm, do the following:

  1. Either:
    • 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 /help/img/idea/2017.3/configure_ignored_files_icon.png on the toolbar.
  2. Click the Add button /help/img/idea/2017.3/new.png on the toolbar.
  3. 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.

      For example, *.iml will ignore all files with the iml extension; *.?ml will ignore all files whose extension ends with ml.

Check project status

WebStorm allows you to check the status of your local working copy compared with 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:

/help/img/idea/2017.3/Git_file_status.png
  • 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:

  • /help/img/idea/2017.3/lineAddedMarker.png line added.
  • /help/img/idea/2017.3/lineChangededMarker.png line changed.

When you delete a line, the following marker appears in the left gutter: /help/img/idea/2017.3/deleted_line_marker.png.

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:

/help/img/idea/2017.3/changeMarkerToolbar.png

You can rollback changes by clicking /help/img/idea/2017.3/rollback.png (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 /help/img/idea/2017.3/compareIcon.png.

Commit changes to the local repository

After you've added new files to the Git repository, or modified files that are already under Git version control and you are happy with their current state, you need to commit the snapshot of your repository to the project history. Do the following:

  1. Invoke the commit dialog in one of the following ways:
    • Press Ctrl+K.
    • In the Local Changes tab of the Version Control tool window, select a changelist or files you want to commit and click the Commit Changes button /help/img/idea/2017.3/icon_commit.png on the toolbar or select Commit Changes on the context menu of the selection.
    • On the main menu, choose VCS | Commit or VCS | Git | Commit File.

    The Commit Changes dialog lists all files that have been modified since the last commit, and all newly added unversioned files.

  2. Enter a commit message and select the Before Commit actions you want WebStorm to perform before committing the selected files to the local repository.
  3. Select the following options in the Git section if necessary:
    • Author: if you are committing changes made by another person, you can specify the author of these changes.
    • Amend commit: select this option if you want to add the local changes to the latest commit (see Combine staged changes with the previous commit (amend commit) for details).
    • Sign-off commit: Select this option if you want to sign off your commit, i.e. to certify that the changes you are about to check in have been made by you, or that you take the responsibility for the code in question.

      When this option is enabled, the following line is automatically added at the end of the commit message: Signed off by: <username>

  4. Click the Commit button or hover the mouse over this button to display one of the following available commit options:
    • Commit and Push: push the changes to the remote repository immediately after the commit.
    • Create Patch: generate a patch based on the changes you are about to commit. In the Create Patch dialog that opens, type the name of the patch file and specify whether you need a reverse patch.
    • Remote Run: run your personal build. This option is only available when you are logged in to TeamCity. Refer to TeamCity plugin documentation for details.

Add a remote repository

To be able to collaborate on your Git project, you need to configure remote repositories that you fetch data from and push to when you need to share your work.

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.

  1. 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.
  2. If you haven't added any remotes so far, the Define remote link will appear instead of a remote name. Click it to add a remote.
  3. 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:

  1. From the main menu, choose VCS | Git | Remotes. The Git Remotes dialog will open.
  2. Click the Add button /help/img/idea/2017.3/new.png on the toolbar or press Alt+Insert.
  3. 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 /help/img/idea/2017.3/edit.png 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 /help/img/idea/2017.3/delete.png on the toolbar, or press Alt+Delete.

Set passwords for Git remotes

Every time you interact with a remote Git repository (for example, during a pull, update, or push operation), it requires authorization. You can configure WebStorm to remember your passwords, so that you do not have to specify your credentials each time authorization is required. The type of authentication depends on which network protocol is used by the remote repository you are trying to access: HTTP or SSH.

If you are using HTTP to access a remote, Git requests credentials from a credential helper when you perform an operation that requires authentication. If no credential helper is found, it returns a prompt to the IDE. If you have configured a password policy, WebStorm looks for credentials in the passwords database. If there is no passwords database, it displays a prompt and you have to enter your login and password.

If your remote uses the SSH protocol, in addition to configuring a password policy, you can choose whether you want to use a native or a built-in SSH executable. To do this, in the Settings/Preferences dialog (Ctrl+Alt+S), select Version Control | Git on the left. From the SSH executable drop-down list, select one of the following options:

  • Built-in: all authorization is performed on the IDE side.
    • If login and password are used for authentication, authorization is performed in accordance with the selected password policy.
    • If an SSH key without a passphrase is used for authentication, WebStorm will access the ~/.ssh/config file and get the key from there.
    • If authentication requires an SSH key with a passphrase, Git looks for it in the credential helper, and, if no credential helper is found, it returns a prompt to the IDE. If you have configured a password policy, WebStorm looks for credentials in the passwords database. If there is no passwords database, it displays a prompt and you have to enter SSH key and a passphrase.
  • Native: all authorization is performed on Git side. No prompt will be displayed, so choose this authorization type if you are using SSH without a passphrase, or the passphrase is saved in a credentials helper, or there is an SSH agent.

Configure a password policy

  1. In the Settings dialog (Ctrl+Alt+S), select Appearance and Behavior | System Settings | Passwords on the left.
  2. Select how you want WebStorm to process passwords for Git remote repositories:
    • In native Keychain: select this option to use native Keychain to store your passwords. This setting is only available for MacOS and Linux.
    • In KeePass: select this option to use the KeePass password manager to store your passwords. When you use the KeePass password manager, a master password will be used to access the file that stores individual passwords. Once WebStorm remembers your passwords, it will not ask for them unless you need to access the passwords database. Enter the password that will be used to access the c.kdbx file in the MasterPassword field.

      You can change the default location of the c.kdbx file in the Database field.

      To import a c.kdbx file, click /help/img/idea/2017.3/icon_viewMode.png and select Import from the drop-down menu, or click /help/img/idea/2017.3/browseButton.png and specify the path to a local file containing your passwords.

      If you want to remove the existing passwords from the database, select Clear.

    • Do not save, forget passwords after restart: select this option if you want your passwords to be reset after you close WebStorm.

Sync with a remote repository

Before you can share the results of your work by pushing your changes to the upstream, you need to synchronize with the remote repository to make sure your local copy of the project is up to date. You can do this in one of the following ways:

Fetch changes from the upstream

When you fetch changes from the upstream, all new data from commits that were made since you last synced with the remote repository is downloaded into your local copy. This new data is not integrated into your local files, and changes are not applied to your code.

Fetched changes are stored as a remote branch, which gives you a chance to review them before you merge them with your files. Since fetch does not affect your local development environment, this is a safe way to get an update of all changes to a remote repository.

To fetch changes, from the main menu choose VCS | Git | Fetch.

Pull changes from the upstream

Pulling changes from a remote repository is a convenient shortcut for fetching and subsequently merging changes. When you pull, you not only download new data, but also integrate it into your local working copy of the project.

To pull changes, do the following:

  1. From the main menu, choose VCS | Git | Pull. The Pull Changes dialog opens.
  2. If your project has several Git repositories, select the path to the local repository that you want to update from the Git Root drop-down list.
  3. If you have several remotes configured for your repository, select the URL of the remote that you want to pull data from in the Remote drop-down list.
  4. Select the branches that you want to fetch changes from and merge into the branch that is currently checked out.
  5. From the Strategy drop-down list, select the merge strategy that will be used to resolve conflicts that occur during merge.
  6. Select the following if necessary:
    • No commit: select this option if you do not want WebStorm to automatically commit merge results. In this case, you can inspect them and adjust if necessary.
    • No fast forward: select this option to generate a merge commit even if the merge was resolved as a fast-forward (i.e. only the branch pointer was updated).
    • Squash commit: select this option to create a single commit on top of the current branch instead of merging one or more branches. It produces the working tree and index state as if a real merge took place, but it does not actually make a commit or move the HEAD.
    • Add log information: select this option if you want WebStorm to populate the log message with one-line descriptions from the actual commits that are being merged in addition to branch names.
  7. Click Pull to fetch and apply changes from the selected remote repository.

Update your project

If you have several project roots, or want to fetch changes from all branches each time you sync with the remote repository, you may find updating your project a more convenient option.

When you perform the update operation, WebStorm pulls changes to all project roots and branches, and merges them into your local working copy (equivalent to pull).

To update your project, do the following:

  1. From the main menu, choose VCS | Update Project or press Ctrl+T. The Update Project dialog opens.
  2. Select the update type (this strategy will be applied to all roots that are under Git version control):
    • Merge: select this option to perform merge during the update. This is equivalent to running git fetch and then git merge, or git pull --no-rebase.
    • Rebase: select this option to perform rebase during the update. This is equivalent to running git fetch and then git rebase, or git pull --rebase (all local commits will be put on top of the updated upstream head).
    • Branch Default: select this option if you want to apply different update strategies for different branches. You can specify the default update type for each branch in the branch.<name> section of the .git/config configuration file.
  3. Specify a method that will be used to save your changes while cleaning your working copy before the update so that your uncommitted changes can be restored after the update is completed:
    • Using Stash: select this option to save local changes in a git stash. This is useful if you need to apply patches with stashed changes outside WebStorm, as they are generated by Git itself.
    • Using Shelve: select this option to put local changes to a shelf. Shelving is done by WebStorm, and patches generated from shelved changes are normally applied inside WebStorm.

Publish your changes (push)

After you have synced with the remote and made sure your local copy of the repository is up-to-date, you can upload (push) the changes you have committed locally to a remote repository to share the results of your work.

WebStorm allows you to upload changes from the current branch to its tracked branch or to any other remote branch.

Do the following:

  1. Press Ctrl+Shift+K or choose VCS | Git | Push from the main menu. The Push Commits dialog opens showing all Git repositories (for multi-repository projects) and listing all commits made in the current branch in each repository since the last push.

    If you have a project that uses multiple repositories that are not controlled synchronously, only the current repository is selected by default (for details on how to enable synchronous repositories control, refer to Version Control Settings: Git).

  2. If there are no remotes in the repository, the Define remote link appears. Click this link and specify the remote name and URL in the dialog that opens. It will be saved and you can edit it later via VCS | Git | Remotes (for details, see Add a remote repository).
  3. If you want to modify the target branch where you want to push, you can click the branch name. The label turns into a text field where you can type an existing branch name, or create a new branch. You can also click the Edit all targets link in the bottom right corner to edit all branch names simultaneously.

    Note that you cannot change the local branch: the current branch for each selected repository will be pushed.

  4. If you want to preview changes before pushing them, select the required commit. The right-hand pane shows the changes included in the selected commit. You can use the toolbar buttons to examine the commit details.
  5. Click the Push button when ready and select which operation you want to perform from the drop-down menu: Push or Force push.

    These choice options are only available if the Allow force push option is enabled (see Version Control Settings: Git), otherwise, you can only perform the push operation.

If push is rejected because your working copy is outdated, WebStorm displays the Push Rejected dialog, provided that the Auto-update if push of the current branch was rejected option in the Git settings page of the Settings dialog is not selected. Do the following:

  1. If your project uses several Git repositories, specify which of them you want to update. If you want to update all repositories, no matter whether push was rejected for them or not, select the Update not rejected repositories as well option. If this option is cleared, only the affected repositories will be updated.
  2. If you want WebStorm to apply the update procedure silently the next time push is rejected using the update method you choose in this dialog, select the Remember the update method choice and silently update in the future option.

    After you leave this dialog, the Auto-update if push of the current branch was rejected checkbox in the Git settings page of the Settings dialog will be selected, and the applied update method will become the default one.

    To change the update strategy, deselect this option to invoke the Push Rejected dialog the next time push of the current branch is rejected, apply a different update procedure, and select the Remember the update method choice option once again.

  3. Select the update method (rebase or merge) by clicking the Rebase or Merge button respectively.

When do I need to use force push?

When you run push, Git will refuse to complete the operation if the remote repository has changes that you are missing and that you are going to overwrite with your local copy of the repository. Normally, you need to perform pull to synchronize with the remote before you update it with your changes.

The --force push command disables this check and lets you overwrite the remote repository, thus erasing its history and causing data loss.

A possible situation when you may still need to perform --force push is when you rebase a pushed branch and then want to push it to the remote server. In this case, when you try to push, Git will reject your changes because the remote ref is not an ancestor of the local ref. If you perform pull in this situation, you will end up with two copies of the branch which you then need to merge.

If you decide to force push the rebased branch and you are working in a team, make sure that:

  • Nobody has pulled your branch and done some local changes to it
  • All pending changes have been committed and pushed
  • You have the latest changes for that branch

Find out who changed what, where and when

WebStorm allows you to trace back all changes in your project: browse the commits history, view history for a specific file, compare revisions, and locate the author of specific changes.

Review project history

WebStorm allows you to review all changes made to the project sources that match the specified filters. To view project history, open the Version Control tool window (Alt+9) and switch to the Log tab. It shows all changes committed to all branches and remote repositories.

Use the search field to search through the list of commits by entering full commit names or messages or their fragments, revision numbers, or regular expressions. You can also filter the commits by branch, user, date and folder (or root and folder for multi-root projects).

You can also click the Go to Hash/Branch/Tag icon /help/img/idea/2017.3/find.png on the toolbar or press Ctrl+F and specify a commit hash, tag or the name of a branch you want to jump to (you will be taken to the latest commit in that branch).

Note that clicking an arrow takes you to the next commit in a long branch:

/help/img/idea/2017.3/jumpToNextCommit.png

In multi-repository projects, the colored stripe on the left indicates which root the selected commit belongs to (each root is marked with its own color). Hover the mouse cursor over the colored stripe to invoke a tip that shows the root path:

/help/img/idea/2017.3/log_root_path.png

Review file history

If you need to review all changes made to a specific file, and identify what exactly was modified in each revision, do the following:

  1. Select the required file in any view (in the Project tool window, in the editor, in the Local Changes tab of the Version Control tool window, etc.).
  2. Select Git | Show History from the main VCS menu or from the context menu of the selection. The History tab is added to the Version Control tool window showing the history for the selected file and allowing you to review and compare its revisions.
  3. To identify which changes were introduced in a specific revision, select it in the list and press Ctrl+D or click the /help/img/idea/2017.3/icon_showDiff.png button on the toolbar. The Differences Viewer will open showing what has changed in this file revision:
    /help/img/idea/2017.3/diffViewer.png

Review the differences between the local and a committed version

If you need to check how a committed file revision is different from its local version, do the following:

  1. Open the Version Control tool window (Alt+9) and switch to the Log tab.
  2. Select the commit you are interested in, and in the right pane select the file in question.
  3. Click the /help/img/idea/2017.3/icon_showDiffLocal.png button on the toolbar.

Locate code author

WebStorm allows you to figure out who introduced which changes to a file by using annotations. Annotation is a form of file presentation that shows detailed information for each line of code, including the revision from which this file 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.

You can get the annotated view of a file opened in the editor, in the Differences Viewer, or selected in any tool window. The Annotate command is available from the context menu (Git | Annotate) or from the left gutter context menu of the editor or the Differences Viewer.

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

/help/img/idea/2017.3/annotate.png

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

You can configure the amount of information displayed in the annotations view by right-clicking the annotations gutter and selecting View from the context menu.

Annotate a previous revision

WebStorm lets you annotate not only the current file revision, but also its 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.
  • 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.

You can also annotate a particular file from the 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.

Watch this video to learn more on how you can benefit from using annotations:

Use patches

Instead of committing your changes, you can put them in a .patch file that you can apply to your sources later, or send by email, etc.

Create a patch

To create a patch based on uncommitted changes, do the following:

  1. Open the Version Control tool window (Alt+9) and switch to the Local Changes tab.
  2. Select a file or a changelist based on which you want to create a patch.
  3. Select Create Patch from the context menu or from the main VCS menu.
  4. In the dialog that opens, make sure that all changes you want to include in the patch are selected, enter a commit comment (optionally) and click Create Patch.
  5. In the Patch File Settings dialog, modify the default patch file location if necessary, and click OK.

If you do not need to save a patch to a file, and want, for example, to send it by email or through a messenger, you can select Copy as Patch to Clipboard from the context menu of the selected file or changelist, and then paste it to a message body.

You can also create a patch based on changes that have already been committed. To create a patch from an entire commit, locate it in the Log view, and select Create Patch from the context menu. If you need to create a patch on a single file, and the corresponding commit contains multiple files, do the following:

  1. Select the required file in any view (in the Project tool window, in the editor, in the Local Changes tab of the Version Control tool window, etc.).
  2. Select Git | Show History from the main VCS menu or from the context menu of the selection. The History tab is added to the Version Control tool window.
  3. Right-click a revision and choose Create Patch from the context menu, or click the Create Patch icon /help/img/idea/2017.3/iconCreatePatch.png on the toolbar.

Apply a patch

To apply changes stored in a file to your sources, do the following:

  1. Select VCS | Apply patch from the main menu.
  2. In the Apply Patch dialog that opens, specify the path to the .patch file you want to apply.
  3. If necessary, click the Map base directory icon /help/img/idea/2017.3/icon_vcs_basic_directory.png to specify a directory relative to which file names in the patch file will be interpreted. You can map a base directory to a single file, directory, or to a selection.
  4. If the source code was edited after a patch was created, conflicts may arise. To check if you patch can be applied without conflicts, click the Show Diff icon /help/img/idea/2017.3/icon_showDiff.png or press Ctrl+D. If there are conflicts, the corresponding lines will be highlighted in red.
  5. If you want to apply changes to files stored in different locations from those specified in the patch, you can strip off the leading directories by using the Strip Directory button /help/img/idea/2017.3/icon_vcs_strip_directory.png.
  6. Select an existing changelist where you want to add the patch from the drop-down list, or specify the name of a new changelist in the Name field, and, optionally, enter a comment to this changelist.
  7. If you want to make this changelist active, select the Set active option.
  8. If you want WebStorm to preserve the context of a task associated with the new changelist on its deactivation and restore the context when the changelist becomes active, select the Track context option (see Managing Tasks and Contexts for details).

You can also copy a patch file content and apply it by choosing VCS | Apply Patch from Clipboard from the main menu. This is convenient when you receive a patch by email, for example, and do not want to save it.

Manage branches

In Git, branching is a powerful mechanism that allows you to diverge from the main development line, for example, when you need to work on a feature, or freeze a certain state of a code base for a release, etc.

In WebStorm, all operations with branches are performed in the Git Branches popup. To invoke it, do one of the following:

  • Click the Git widget in the Status bar:
    /help/img/idea/2017.3/git_widget.png
  • Invoke the VCS Operations popup by choosing VCS Operations Popup from the main menu, or press Alt+Back Quote and select Branches there.
  • From the main menu, choose VCS | Git | Branches.
  • Right-click any file in the editor, and in the context menu choose Git | Repository | Branches.

If you have many branches, you can choose whether you want to display all of them in the Branches popup, or just the favorites. To do this, toggle the Show Only Favorites and the Show x More commands at the bottom of the Branches popup.

To mark a branch as a favorite, hover the mouse cursor over the branch name, and click the star outline that appears on the left: /help/img/idea/2017.3/GitFavoriteBranch.png. The master branch is marked as a favorite by default.

The name of the branch that is currently checked out is displayed in the Git widget in the Status bar.

Create a new branch

If you want to create a new branch, for example to work on a new feature, do the following

  1. In the Branches popup, choose New Branch.
  2. In the dialog that opens, specify the branch name, and make sure the Checkout branch option is selected if you want to switch to that branch.

The new branch will start from the current HEAD. If you want to start a branch from a previous commit instead of the current branch HEAD, select this commit in the Log and select New Branch from the context menu.

Checkout a branch as a new local branch

If you want to work in a branch created by someone else, you need to check it out to create a local copy of that branch:

  1. In the Branches popup, select a branch that you want to check out locally from Remote Branches, or Common Remote Branches if your project has several roots and synchronous branch control is enabled, or from Repositories | Remote Branches if it is disabled, and choose Checkout as new local branch from the list of available operations.
  2. Enter a new name for this branch if necessary, or leave the default name that corresponds to the remote branch, and click OK.

Switch between branches

When multitasking, you often need to jump between branches to commit unrelated changes. To switch to a different branch, in the Branches popup, select the branch that you want to switch to under Local Branches and choose Checkout from the list of available operations. What happens next depends on whether there are conflicts between your local changes that you have not committed yet, and the branch that you are going to check out:

  • If your working tree is clean (i.e. you have no uncommitted changes), or your local changes do not conflict with the specified branch, this branch will be checked out (a notification will pop up in the bottom-left corner of the WebStorm window).
  • If your local changes will be overwritten by checkout, WebStorm displays a list of files that prevent you from checking out the selected branch, and suggests to choose between Force Checkout and Smart Checkout.

    If you click Force Checkout, your local uncommitted changes will be overwritten and you will lose them.

    If you click Smart Checkout, WebStorm will stash uncommitted changes, check out the selected branch, and then unstash the changes. If a conflict occurs during the unstash operation, you will be prompted to merge the changes. For details, see Resolve conflicts.

Compare branches

If you want to check how two branches have diverged from each other, you can compare them. To do this, from the Branches popup select the branch that you want to compare with the current branch, and choose Compare from the list of available operations.

In the dialog that opens, the Log tab shows a list of all commits that exist in one branch and do not exist in the other. When you select a commit, the right pane displays a list of files that were affected by this commit. You can click the Show Diff icon /help/img/idea/2017.3/icon_showDiff.png on the toolbar to see how exactly the selected file was changed in this commit.

The Files tab shows a list of all files that have diverged between the two branches. Clicking /help/img/idea/2017.3/icon_showDiff.png shows the differences between the selected file in the current branch and in the branch you are comparing it with.

Apply changes from one branch to another

In Git, there are several ways to integrate changes from one branch into another:

Merge branches

Suppose you have created a feature branch to work on a specific task, and want to integrate the results of your work into the main code base after you have completed and tested your feature:

/help/img/idea/2017.3/feature_branch_diagram.png

Merging your branch into master is the most common way to do this.

It is very common that while you are working in your feature branch, your teammates continue to commit their work to master:

/help/img/idea/2017.3/feature_branch_diverge_from_master_diagram.png

When you run merge, the changes from your feature branch are integrated into the HEAD of the target branch:

/help/img/idea/2017.3/merge_result_diagram.png
Git creates a new commit (M) that is referred to as a merge commit that results from combining the changes from your feature branch and master from the point where the two branches diverged.

To merge branches, do the following:

  1. Switch to the target branch that you want to integrate the changes to.
  2. Invoke the branches popup , and select the branch that you want to merge into the target branch.
  3. Choose Merge from the submenu.

If your working tree is clean (i.e. you have no uncommitted changes), and no conflicts occur between your feature branch and the target branch, Git will merge the two branches, and the merge commit will appear in the Log:

/help/img/idea/2017.3/merge_commit.png

If conflicts occur between your branch and the target branch, you will be prompted to resolve them (see Resolve conflicts for details).

If you have local changes that will be overwritten by merge, WebStorm will suggest performing Smart merge. If you select this option, WebStorm will stash uncommitted changes, perform merge, and then unstash the changes.

Rebase branches

When you rebase a branch onto another branch, you apply the commits from the first branch on top of the HEAD commit in the second branch instead of merging them into the target branch.

Suppose you have created a feature branch to work on a specific task and make several commits to that branch:

/help/img/idea/2017.3/feature_branch_diagram.png

While you develop in your branch, your teammates continue to commit their work to master:

/help/img/idea/2017.3/feature_branch_diverge_from_master_diagram.png

When you perform the rebase operation you integrate changes you have done in your feature branch to the master branch by applying your commits on top of the current HEAD commit in master:

/help/img/idea/2017.3/rebase_result_diagram.png

To rebase the current branch on top of another branch
To rebase the branch that is currently checked out on top of another branch, do the following:
  1. Invoke the branches popup and select the branch the you want to rebase the current branch onto.
  2. Choose Rebase onto from the list of available actions.
To rebase a branch on top of the current branch

To rebase a branch on top of the branch that is currently checked out, do the following:

  1. Invoke the branches popup and select the branch that you want to rebase on top of the current branch.
  2. Choose Checkout with Rebase from the list of available actions.

For details on how to skip or squash commit during a rebase, refer to Edit project history by performing interactive rebase.

Watch this video to see how a merge or a rebase operation are reflected in the Log view:


Apply changes from a specific commit to another branch (cherry-pick)

Sometimes you only need to apply a single commit to a different branch instead of rebasing or merging an entire branch. This may be useful, for example, if you are working in a feature branch and want to integrate a hotfix from master that was committed after the two branches have diverged. Or you may want to backport a fix to a previous release branch, etc.

WebStorm allows you to do so by using the Cherry-pick action:

  1. Switch to the target branch that you want to integrate the changes to.
  2. Open the Version Control tool window (Alt+9) and switch to the Log tab.
  3. Locate the commit containing the changes you want to cherry pick.

    Note that the log lists all commits. To reduce the number of items in the list, you can filter commits by branch, user or date. You can also click the Highlight non-picked commits button /help/img/idea/2017.3/non_picked_commits.png to grey out the commits that have already been applied to the current branch. If you know the commit hash, or are looking for a tagged commit, you can also use the Go to Hash / Branch / Tag action (press Ctrl+F in the Log view, or click /help/img/idea/2017.3/find.png on the toolbar).

  4. Select the required commit. Use the information in the Commit Details area if necessary.
  5. Click the Cherry-pick button cherryPickButton.png on the toolbar. WebStorm will display the Commit Changes dialog with the automatically generated commit message. If you want to review the changes or even modify the code before committing it to the target branch, you can do so in the difference viewer available from this dialog.
  6. When done, click Commit to cherry-pick the selected changes.

    Note that if you click Cancel, a separate changelist will be created with the selected changes that you can see in the Local Changes tab. You can review these changes and commit them later if necessary.

Delete branches

After you have integrated the changes from a feature branch into the main line of development, you can delete the branch you do not need anymore:

  1. Invoke the branches popup and select the branch you want to delete.
  2. Choose Delete from the submenu.

After you have deleted a branch, a notification will be displayed in the bottom right corner from which you can restore the deleted branch:

/help/img/idea/2017.3/deleted_branch_notification.png

If the branch contained commits that have not yet been merged to its upstream branch or to the current branch, it will still be deleted immediately (equivalent to the git branch --D or git branch --delete --force command), but the notification will also contain a link allowing you to view the unmerged commits.

If the deleted branch was tracking a remote branch, you will also be able to remove the remote branch from this notification.

Resolve conflicts

When you work in a team, you may come across a situation when somebody pushes changes to a file you are currently working on. If these changes do not overlap (i.e. changes were made to different lines of code), the conflicting files are merged automatically. However, if the same lines were affected, Git cannot randomly pick one side over the other, and asks you to resolve the conflict.

In Git, conflicts may arise when you attempt to perform one of the following operations: pull, merge, rebase, cherry-pick, unstash changes or apply a patch. If there are conflicts, these operations will fail, and you will be prompted to accept the upstream version, prefer your version, or merge the changes:

/help/img/idea/2017.3/merge_conflicts_dialog.png

WebStorm provides a tool for resolving conflicts locally. This tool consists of three panes. The left pane shows the read-only local copy; the right pane shows the read-only version checked in to the repository. The central pane shows a fully-functional editor where the results of merging and resolving conflicts are displayed. Initially, the contents of this pane are the same as the base revision of the file, that is, the revision from which both conflicting versions are derived.

To resolve conflicts, do the following:

  1. Click Merge in the Files Merged with Conflicts dialog, or select the conflicting file in the editor and choose VCS | <your_VCS> | Resolve Conflicts from the main menu.
  2. To automatically merge all non-conflicting changes, click /help/img/idea/2017.3/applyNotConflicts.png (Apply All Non-Conflicting Changes) on the toolbar. You can also use the /help/img/idea/2017.3/applyNotConflictsLeft.png (Apply Non-Conflicting Changes from the Left Side) and /help/img/idea/2017.3/applyNotConflictsRight.png (Apply Non-Conflicting Changes from the Right Side) to merge non-conflicting changes from the left/right parts of the dialog respectively.
  3. To resolve a conflict, you need to select which action to apply (accept /help/img/idea/2017.3/chevron_button.png or ignore /help/img/idea/2017.3/ignore_button.png) to the left (local) and the right (repository) version, and check the resulting code in the central pane:
    /help/img/idea/2017.3/resolveConflict.png

    For simple conflicts (for example, if the beginning and the end of the same line have been modified in different file revisions), the Resolve option is available that allows merging the changes in one click:

    Such conflicts are not resolved with the Apply All Non-Conflicting Changes action since you must make sure that they are resolved properly.

    /help/img/idea/2017.3/simple_conflict_resolve.png
  4. It may also be useful to compare different versions to resolve a conflict. Use the /help/img/idea/2017.3/conflicts_compare_options.png toolbar button to invoke the list of options. Note that Base refers to the file version that the local and the repository versions originated from (initially displayed in the middle pane), while Middle refers to the resulting version.
  5. Review merge results in the central pane and click Apply.

Handle conflicts related to LF and CRLF line endings

Quite often, people working in a team and contributing to the same repository use different operating systems. This may result in problems with line ending, because Unix, Linux and MacOS us LF, and Windows uses CRLF to mark the end of a line.

WebStorm displays the discrepancies in line endings in the Differences Viewer, so you can fix them manually. If you want Git to solve such conflicts automatically, you need to set the core.autocrlf attribute to true on Windows and to input on Linux and MacOS (for more details, see Dealing with line endings). You can change the configuration manually by running git config --global core.autocrlf true on Windows or git config --global core.autocrlf input on Linux and macOS.

However, WebStorm can automatically analyze your configuration, warn you if you are about to commit CRLF into a remote repository, and suggest setting the core.autocrld setting to true or input depending on your operating system.

To enable smart handling of LF and CRLF line separators, open the Settings dialog (Ctrl+Alt+S), and select the Version Control | Git node on the left. Enable the Warn if CRLF line separators are about to be committed option.

After you have enabled this option, WebStorm will display the Line Separators Warning Dialog each time you are about to commit a file with CRLF separators, unless you have set any related Git attributes in the affected file (in this case, WebStorm supposes that you clearly understand what you are doing and excludes this file from analysis).

In the Line Separators Warning Dialog, click one of the following:

  • Commit As Is to ignore the warning and commit a file with CRFL separators.
  • Fix and Commit to have the core.autocrlf attribute set to true or input depending on your operating system. As a result, CRLF line separators will be replaced with LF before the commit.

Work on several features simultaneously

Sometimes you need to switch between different tasks with things left unfinished and then return back to them. WebStorm provides you with a few ways to conveniently work on several different features without losing your work:

Shelve and unshelve changes

Shelving is temporarily storing pending changes you have not committed yet. This is useful, for example, if you need to switch to another high priority task and you want to set your changes aside to work on them later.

With WebStorm, you can shelve both separate files and entire changelists.

Once shelved, a change can be applied as many times as you need by unshelving and subsequently restoring it on the shelf.

Shelve changes

  1. Open the Version Control tool window (Alt+9) and switch to the Local Changes tab.
  2. Select the files or a changelist you want to put to a shelf. On the main Version Control menu or on the context menu of the selection, choose Shelve changes.
  3. In the Shelve Changes dialog, review the list of modified files.
  4. In the Commit Message field, enter the name of the shelf to be created and click the Shelve Changes button.

You can also shelve changes silently, without displaying the Shelve Changes dialog. To do this, select a file or a changelist you want to shelve, and click the Shelve Silently icon /help/img/idea/2017.3/shelve_silently_icon.png on the toolbar, or press Ctrl+Alt+H. The name of the changelist containing the changes you want to shelve will be used as the shelf name.

Unshelve changes

Unshelving is moving postponed changes from a shelf to a pending changelist. Unshelved changes can be filtered out from view or removed from the shelf.

  1. In the Shelf tab of the Version Control tool window, select a changelist or files you want to unshelve.
  2. Press Ctrl+Shift+U or choose Unshelve from the context menu of the selection.
  3. In the Unshelve Changes dialog that opens, specify the changelist you want to restore the unshelved changes to in the Name field. You can select an existing changelist from the drop-down list or type a name for a new changelist to be created containing the unshelved changes. You can enter the description of the new changelist in the Comment field (optional).

    If you want to make the new changelist active, select the Set active option. Otherwise, the current active changelist remains active.

  4. If you want WebStorm to preserve the context of a task associated with the new changelist on its deactivation and restore the context then the changelist becomes active, select the Track context option (see Managing Tasks and Contexts for details).
  5. If you want to remove the changes you are about to unshelve, select the Remove successfully applied files from the shelf option. The unshelved files will be removed from this shelf and added to another changelist and marked as applied. They will not be removed completely until deleted explicitly by clicking the /help/img/idea/2017.3/clean_unshelved_changes.png icon on the toolbar, or selecting Clean Already Unshelved from the context menu.
  6. Click OK. If conflicts occur between the patched version and the current version, resolve them as described in Resolving Conflicts.

You can also unshelve changes silently, without displaying the Unshelve Changes dialog. To do this, select a file or a changelist you want to unshelve, and click the Unshelve Silently icon /help/img/idea/2017.3/unshelve_silently_icon.png on the toolbar, or press Ctrl+Alt+U. The unshelved files will be moved to the active pending changelist.

Restore unshelved changes

WebStorm lets you reapply unshelved changes if necessary. All unshelved changes can be reused until they are removed explicitly by clicking the /help/img/idea/2017.3/clean_unshelved_changes.png icon on the toolbar, or selecting Clean Already Unshelved from the context menu.

To restore applied changes on the shelf do the following:

  1. Make sure that the Show Already Unshelved /help/img/idea/2017.3/show_already_unshelved.png toolbar option is enabled.
  2. Select the files or the shelf you want to restore.
  3. On the context menu of the selection, choose Restore.

Apply external patches

You can import patches created inside or outside WebStorm and apply them as shelved changes.

  1. In the Shelf tab of the Version Control tool window, choose Import Patches from the context menu.
  2. In the dialog that opens, select the patch file to apply. The selected patch appears in the Shelf tab as a shelf.
  3. Select the newly added shelf with the patch and choose Unshelve Changes from the context menu of the selection.

Automatically shelve base revision

It may be useful to configure WebStorm to always shelve base revisions of files that are under Git version control. To do this, open the Settings dialog (Ctrl+Alt+S), select the Version Control | Shelf node on the left and select the Shelve base revisions of files under distributed version control systems option.

If this option is enabled, the base revision of files will be saved to a shelf that will be used during a 3-way merge if applying a shelf leads to conflicts. If it is disabled, WebStorm will look for the base revision in the project history, which may take a while; moreover, the revision that the conflicting shelf was based on may be missing (for example, if the history was changed as a result of the rebase operation).

Change the default shelf location

By default, the shelf directory is located under your project directory. However, you may want to change the default shelf location. This can be useful, for example, if you want to avoid deleting shelves accidentally when cleaning up your working copy, or if you want to store them in a separate repository allowing shelves to be shared among your team members.

  1. Open the Settings dialog (Ctrl+Alt+S) and select the Version Control | Shelf node on the left.
  2. Click the Change Shelves Location button and specify the new location in the dialog that opens.
  3. If necessary, select the Move shelves to the new location option to move existing shelves to the new directory.

Watch this video tutorial on how to benefit from shelves to be able to switch to a different task without losing unfinished work:

Stash changes

Sometimes it may be necessary to revert your working copy to match the HEAD commit but you do not want to lose the work you have already done. This may happen if you learn that there are upstream changes that are possibly relevant to what you are doing, or if you need to make some urgent fixes.

Stashing involves recording the difference between the HEAD commit and the current state of the working directory (stash). Changes to the index can be stashed as well.

Unstashing involves applying a stored stash to a branch.

You can apply a stash to an existing branch or create a new branch on its basis.

A stash can be applied as many times as you need to any branch you need, just switch to the required branch. Keep in mind that:

  • Applying a stash after a series of commits results in conflicts that need to be resolved.
  • You cannot apply a stash to a "dirty" working copy, that is a working copy with uncommitted changes.

Save changes to a stash

  1. From the main menu, choose VCS | Git | Stash Changes.
  2. In the Stash dialog that opens, select the appropriate Git root and make sure that the correct branch is checked out.
  3. In the Message field describe the changes you are about to stash.
  4. To stash local changes and bring the changes staged in the index to your working tree for examination and testing, select the Keep index option.
  5. Click Create Stash.

Apply a stash

To apply a stash, do the following:

  1. From the main menu, choose VCS | Git | Unstash Changes.
  2. Select the Git root where you want to apply a stash, and make sure that the correct branch is checked out.
  3. Select the stash you want to apply from the list.

    If you want to check which files are affected in the selected stash, click View.

  4. To remove the selected stash after it is applied, select the Pop stash option.
  5. To apply stashed index modifications as well, select the Reinstate Index option.
  6. If you want to create a new branch on the basis of the selected stash instead of applying it to the branch that is currently checked out, type the name of that branch in the As new branch field.

To remove a stash, select it in the list and click Drop. To remove all stashes, click Clear.

Group changes into different changelists

When you are working on several related features, you may find it convenient to group changes into different changelists. This approach has its pros and cons as opposed to using feature branches to work on multiple tasks.

Pros:

  • You can easily switch between different logical sets of changes and commit them separately from each other.
  • Unlike using branches for the same purpose, you have all your changes at hand without having to switch between branches which can take a while if your project is really large.
  • It's convenient to test how different features work together.
  • You can remote-run a changelist on a build server.

Cons:

  • While using changelists may seem a more lightweight option compared to branches, it's not safe as there's no backup for your changes until you have committed and pushed them. If something happens to your local working copy, all your changes will be lost as they are not part of Git project history.
  • Using changelists only works if changes do not overlap. If different tasks affect the same file, you cannot separate these changes and put them into separate changelists.
  • No atomic testing of features is possible.
  • No collaboration on the same feature is possible. Also, you cannot make contributions from different machines unless you send patches with changes through email, which may not be very convenient.

All changelists are displayed in the Local Changes tab of the Version Control tool window. All modified files are automatically placed in the active changelist, which is the Default changelist unless you have created a different one and made it active.

To create a new changelist, click /help/img/idea/2017.3/add.png on the toolbar.

To make a non-default changelist active, right-click it and choose Set Active Changelist from the context menu.

To move changes between changelists, select the file you want to move and click /help/img/idea/2017.3/moveChangelistItems.png on the toolbar, or choose Move to Another Changelist from the context menu.

  1. Select the Set active option if you want to make the changelist with the changes you are about to discard the active changelist.
  2. Select the Track context option if you want WebStorm to remember your context and reload currently opened files in the editor when this changelist becomes active.

Use feature branches

A branch in Git represents an independent line of development, so if you are working on a separate feature that you want to complete and test before you are ready to share the results of your work and integrate them into master, doing it in a feature branch is the best solution. This way you can make sure unstable code is not committed to the main code base of your project, and you can easily switch to other tasks if necessary.

Pros:

  • As opposed to using changelists to group changes, using feature branches is safe. After you've committed changes to Git, they become part of Git project history, so you can always restore your commit through Git reflog even if you corrupt your working tree. After you've pushed your changes, they are backed up.
  • You can develop parallel non-related features and test them atomically.
  • When you've finished development in your branch, you can reorder or squash commits, so that your history is linear and clean.
  • It is easy to collaborate on your feature, or develop it from different machines.

Cons:

  • It can take time to switch branches on really large projects.
  • It's not very convenient to test related features together.
  • You have to learn a workflow for using feature branches and integrating your changes into the main code base.

Workflow for using feature branches

There are two major approaches for using feature branches and integrating your changes into the main code base:

Use merge to integrate changes from a feature branch

The major benefit of the merge option is full traceability, as commits merged into the main code base preserve their original hash and author, and all commits that are part of one feature can be grouped together.

This workflow is good for projects where committing changes to the main code base involves pull requests or an hierarchical approval procedure, as existing branches are not changed in any way.

The main drawback of this approach is that extraneous merge commits are created each time you need to incorporate changes, which intensely pollutes project history and makes it difficult to read.

The merge option workflow involves the following steps:

  1. Create a branch for your separate line of development.
  2. Commit your changes while you develop.
  3. Push your branch to a remote repository. This should be done for backup, and so that you can collaborate or work from different machines.
  4. Switch to a different branch when you need to perform work that is not related to your feature.
  5. Have your feature reviewed and tested, and make the necessary fixes.
  6. When you are ready to integrate the results of your work into the main branch (e.g. master), do the following:
Use rebase to integrate changes from a feature branch

The major benefit of this option is that you get a clean project history that is easy for others to read and understand. Your log does not contain unnecessary merge commits produced by the merge operation, and you get linear history that is easy to navigate and search through.

When deciding to adopt this workflow, you should keep in mind, however, that rebase rewrites project history as it creates new commits for each commit in the original feature branch, so they will have different hashes, which obstructs traceability.

The rebase option involves the following steps:

  1. Create a branch for your separate line of development.
  2. Commit your changes often while you develop.
  3. Push your branch to a remote repository. This should be done for backup, and so that you can collaborate or work from different machines.
  4. Rebase your feature branch onto master from time to time. It only makes sense to do this if your feature branch is a long one. This is useful to:
    • make sure your feature branch and master do not fall too far apart.
    • avoid resolving numerous conflicts when you finally integrate your changes into the main code base. When you rebase regularly, you can resolve conflicts iteratively and do not end up struggling with a long diff.
    • speed up checking out branches, as switching between branches gets slower as soon as they diverge sufficiently.

    Rebasing involves the following steps:

    • Fetch changes from the remote, or pull changes into the master branch.
    • Rebase your branch onto master.
    • Force push the results of the rebase operation to your feature branch.

  5. Switch to master when you need to perform work that is not related to your feature. When you turn back to your feature branch, perform Checkout with rebase.
  6. Have your feature reviewed and tested, and make the necessary fixes.
  7. Perform Interactive Rebase when your feature has been completed. This allows you to reorder and squash commits to make your feature branch history look nice and clean.
  8. When you are ready to integrate the results of your work into the main branch (e.g. master), do the following:
    • Checkout the master branch.
    • Merge your branch with master. Since master has not diverged, Git will just move the pointer forward to the latest commit of the feature branch instead of creating a new merge commit (this is referred to as a fast-forward merge).
    • Delete the feature branch.
    • Push.

Undo changes

WebStorm allows you to undo something at any stage. This section explains how to:

Revert uncommitted changes

You can always undo the changes you've done locally before you have committed them:

  1. Open the Version Control tool window (Alt+9) and switch to the Local Changes tab.
  2. In the active changelist, select one or more files that you want to revert, and select Revert from the context menu, or press Ctrl+Alt+Z. All changes done to the selected files since the last commit will be undone, and they will disappear from the Local Changes view.

Undo the last commit

WebStorm allows you to undo the last commit in the current branch (i.e. HEAD):

  1. Open the Version Control tool window (Alt+9) and switch to the Log tab.
  2. Select the last commit in the current branch and choose Undo Commit from the context menu.
  3. In the dialog that opens, select a changelist where the changes you are going to discard will be moved. You can either select an existing changelist from the Name drop-down list, or specify the name of a new changelist (the commit message is used by default).
  4. Select the Set active option if you want to make the changelist with the changes you are about to discard the active changelist.
  5. Select the Track context option if you want WebStorm to remember your context and reload currently opened files in the editor when this changelist becomes active.

Revert a pushed commit

If you notice an error in a specific commit that has already been pushed, you can revert that commit. This operation results in a new commit that reverses the effect of the commit you want to undo. Thus, project history is preserved, as the original commit remains intact.

  1. Locate the commit you want to revert in the Log view, right-click it and select Revert from the context menu. The Commit Changes dialog will open with an automatically generated commit message.
  2. If the selected commit contains several files, and you only need to revert some of them, deselect the files you do not want to touch.
  3. Click Commit to commit a changeset that reverts changes to the selected files in this particular commit.

Reset a branch to a specific commit

If you notice an error in a set of recent commits and want to redo that part, you can roll back your repository to a specific state. This is done by resetting the current branch HEAD to a specified commit (and optionally resetting the index and working tree if you prefer not to reflect the undo in the history).

  1. Open the Version Control tool window (Alt+9) and switch to the Log tab.
  2. Select the commit that you want to move HEAD onto and select Reset Current Branch to Here from the context menu.
  3. In the Git Reset dialog that opens, select how you want your working tree and the index to be updated and click Reset:
    • Soft: all changes from commits that were made after the selected commit will be staged (i.e. they will be moved to the Local Changes view so that you can review them and commit later if necessary).
    • Mixed: changes made after the selected commit will be preserved but will not be staged for commit.
    • Hard: all changes made after the selected commit will be discarded (both staged and committed).
    • Keep: committed changes made after the selected commit will be discarded, but local changes will be kept intact.

Get a previous revision of a file

If you need to revert a single file instead of discarding a whole commit that includes changes to several files, you can return to a particular version of that file:

  1. Select the required file in any view (in the Project tool window, in the editor, in the Local Changes tab of the Version Control tool window, etc.).
  2. Select Git | Show History from the main VCS menu or from the context menu of the selection. The History tab is added to the Version Control tool window showing the history for the selected file and allowing you to review and compare its revisions.
  3. When you've identified the revision you want to roll back to, select it in the list and choose Get from the context menu.

Use tags to mark specific commits

Git allows you to attach tags to commits to mark some points in the project history as being important, so that you can refer to them in the future. For example, you can tag a commit that corresponds to a release version, instead of creating a branch to capture a release snapshot.

Assign a tag to a commit

  1. From the main menu, choose VCS | Git | Tag.
  2. In the Tag dialog that opens, under Git Root, select the path to the local repository in which you want to tag a commit, and specify the name of the new tag.
  3. In the Commit field, specify the commit that you want to tag. You can enter the commit hash, or use an expression, for example: <branch>~<number of commits backwards between the latest commit (HEAD) and the required commit> (Refer to Git commit naming conventions for details).
  4. If you enter some comment in the Message field, an annotated tag will be created instead of a regular one. Meta-data for annotated tags contains the name of the user who created them, so they allow you to check who placed them.
  5. Click Create Tag. The tag will be shown in the Log view:
    /help/img/idea/2017.3/tagged_commit.png

Reassign an existing tag

If you've placed a tag on a wrong commit, and want to reassign it (for example, to indicate a commit for a release version), do the following:

  1. From the main menu, choose VCS | Git | Tag.
  2. In the Tag dialog, in the Tag Name field specify the name of an already existing tag that you want to reassign.
  3. Select the Force option.
  4. In the Commit field, specify the commit where the tag shall be moved and click Create Tag.

Jump to a tagged commit

  1. Open the Version Control tool window (Alt+9) and switch to the Log tab.
  2. Click the Go To Hash/Branch/Tag icon /help/img/idea/2017.3/find.png on the toolbar, or press Ctrl+F.
  3. Enter the tag name (code completion suggests tag names as you type) and press Enter.

Check out a tagged commit

Suppose you marked a commit that corresponds to a release version with a tag, and now you want to review the snapshot of your project at that point in time. You can do this by checking out a tagged commit. Do one of the following:

  • Locate the tagged commit that you want to checkout, right-click it and select Checkout Revision from the context menu.
  • Invoke the branches popup, click Checkout Tag or Revision and type in the tag name.

Note that this operation results in a detached HEAD, which means you are no longer in any branch. You can use this snapshot for inspection and experiments. However, if you want to commit changes on top of this snapshot, you will need to create a branch.

Edit project history

Git allows you to edit your project history if at some point you need to rewrite your commits as if you made them in a different way. In WebStorm you can:

Combine staged changes with the previous commit (amend commit)

Sometimes you may find yourself in a situation when you commit too early and forget to add some files or notice an error in the last commit that you want to fix without it being reflected in the project history.

WebStorm allows you to do this by using the Amend commit option that combines the previous commit with the current changes, and you end up with a single commit instead of two different commits.

To amend the previous commit, do the following:

  1. Invoke the Commit changes dialog and select the changes that you want to use to fix up the previous commit.
  2. Either press Ctrl+K, click /help/img/idea/2017.3/icon_commit.png on the toolbar, or select Commit from the context menu.
  3. In the Commit Changes dialog that opens, select the Amend commit option on the right before committing your changes.

Edit a commit message

If the only thing you need to change is a commit message, you can edit it without making any other changes:

  1. Locate the commit whose message you want to edit in the Log view, right-click it and select Reword from the context menu, or press F2.
  2. In the dialog that opens, enter a new commit message and click OK.

Edit project history by performing interactive rebase

Git allows you to edit project history for the sake of making it linear and meaningful by performing interactive rebase. Instead of applying all commits from a branch in the same order they were made on top of another branch, interactive rebase allows you to alter individual commits, change their order, squash commits into one, skip commits that contain extraneous changes, etc.

This allows you to clean up a messy commits history when you integrate changes from your feature branch, but keep in mind that re-writing commits history may lead to data loss.

To perform an interactive rebase:

  1. Initiate a rebase
  2. Select the Interactive option in the Rebase Branches dialog. The Interactive Rebase dialog will be displayed containing the list of all commits from the source branch.
  3. Use the Action drop-down list to apply the following actions to commits:
    • Pick: applies the selected commit as is.
    • Edit: select this option to edit the files affected by this commit or the commit message before applying this commit.
    • Skip: ignores the selected commit.
    • Squash: select this option to combine the selected commit with the previous one.
    • Reword: select this option to edit the commit message before applying this commit.
    • Fixup: select this option to combine the selected commit with the previous one and use the message from the previous commit with the "fixup!" prefix.
  4. Use the Move Up and Move Down buttons to modfiy the order in which commits should be applied.

Manage projects hosted on GitHub

WebStorm allows you to manage projects controlled by Git that are hosted on GitHub without leaving the IDE.

Register a GitHub account in WebStorm

To retrieve data from a repository hosted on GitHub, and to be able to share your projects, you need to register your GitHub account in WebStorm. You can also create an account on GitHub without leaving the IDE if you do not have one yet.

In either case, WebStorm remembers your login and password, so you do not have to specify your credentials each time you retrieve data from a remote, or push your commits.

Register an existing GitHub account

GitHub offers two-factor authentication to improve the protection of user accounts.

If you enable two-factor authentication and you use SSH to access your repositories, you can choose any authentication type - password or token.

If you use the HTTPs protocol to access your remote repositories on GitHub, you need to configure an Access token and use it to authenticate, otherwise remote Git operations will fail. When prompted for credentials, either enter the token as your username and leave the password field empty, or specify the token instead of your password.

To register your account, do the following:

  1. Invoke the Settings dialog (Ctrl+Alt+S) and select Version Control | GitHub in the left pane.
  2. Select the type of authentication that you want to use from the Auth Type drop-down list:
    • Password. If this option is selected and you have two-factor authentication enabled in your GitHub account settings, you will be asked to enter an authentication code each time WebStorm requires you to log in to your GitHub account.
    • Token (recommended by GitHub for authentication from third-party applications, as it does not require WebStorm to remember your password).
  3. Specify your credentials depending on the selected authentication type, and click OK.

Create a new GitHub account

  1. Invoke the Settings dialog (Ctrl+Alt+S) and select Version Control | GitHub in the left pane.
  2. Click the Sign up link.
  3. On the Sign up for GitHub page that opens in the browser, choose the account plan (free or paid), and specify the requested information. When you are done creating an account, the GitHub Welcome Page is displayed.
  4. Return to GitHub settings and specify your credentials for WebStorm to register them.

Checkout a project from GitHub

WebStorm allows you to check out (clone) a repository from GitHub and create a new project based on it:

  1. From the main menu, choose VCS | Checkout from Version Control | GitHub.
  2. In the Clone Repository dialog that opens, specify the URL of the repository that you want to clone, or select a repository from the list that contains all GitHub projects associated with your account and the organization that your account belongs to.
  3. In the Parent Directory field, specify the path where the folder for your local Git repository will be created.
  4. In the Directory Name field, specify the name of the folder into which the repository will be cloned.
  5. Click Clone. If you want to create a WebStorm 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.

Share a project on GitHub

If you want to add a remote repository for your project on GitHub, do the following:

  1. Open the project you want to share.
  2. From the main menu, choose VCS | Import into Version Control | Share Project on GitHub.

    If you have already registered your login and password in WebStorm, connection to GitHub will be established using these credentials.

    If you have not registered your GitHub credentials in WebStorm, the Login to GitHub dialog opens. Specify your login and password, or create a new account there.

  3. When connection to GitHub has been established, the Share Project on GitHub dialog opens. Specify the new repository name and enter a description of your project's main functionality.

    You can select the Private option if you do not want to allow public access to your repository for other GitHub users (note that this option is unavailable for free accounts).

  4. Click Share to initiate a new repository and upload project sources to it.

Contribute to somebody else's projects

If you want to contribute to a project hosted on GitHub that you do not have rights to push to, follow this workflow:

  • Create a fork of the project you want to contribute to, i.e. a copy of the original repository on GitHub.
  • Clone this fork to create a local repository.
  • Make changes to your copy of the original project.
  • When you are ready to share the results of your work, rebase your fork on the current HEAD of the master branch in the original project to make sure your changes do not conflict with new commits that were pushed after you created your fork.
  • Create a pull request so that you can tell others about the changes you've made, and ask for comments or review. Note that a pull request is merged into the original repository only after approval.

Fork a project

Open the project that you want to fork on GitHub and click /help/img/idea/2017.3/github_fork.png

A copy of the original project will be created under your account. To make changes to this project, you need to clone it to create a local repository.

Watch this video tutorial on how to keep your fork of a project up to date:

Rebase a fork

From the main menu, choose VCS | Git | Rebase my GitHub fork. Your fork will be rebased onto the HEAD commit in the master branch of the original project your created your fork from.

Create a pull request

By creating a pull request, you tell others about the changes you've pushed to your fork, so that they can be reviewed, discussed, and integrated into the base branch. To create a pull request, do the following:

  1. From the main menu, choose VCS | Git | Create Pull Request. The Create Pull Request dialog opens.
  2. Under Base Fork, specify the project that you want to send the pull request to. Either select a repository from the list populated by WebStorm, or click Select Other Fork.
  3. Under Base Branch, specify the branch in the target project that your changes will be applied to. Click Show Diff to review the list of commits that will be included in the pull request. To view a commit details, select it and switch to the Log tab of the Version Control tool window, where you can see a list of files included in the selected commit, view diff, etc.
  4. Specify the name for your pull request in the Title field, and, optionally, provide a description of the changes to be applied through your request.

Share code by using gists

Gists allow you to share your code. You can share code snippets, entire files, or even applications. You can also use gists to save and share console output when running, debugging, or testing your code.

To create a gist, do the following:

  1. Select a code fragment in the editor, or files and folders in the Project tool window. To save console output to a gist, right-click anywhere in the tool window or tab that contains that output.
  2. On the context menu of the selection, choose Create Gist.
  3. In the Create Gist dialog that opens, specify the name for your gist under Filename, and enter a description of the code you are going to publish.
  4. Select the Private option to create the so-called secret gist. Secret gists are not searchable and do not show up in Discover. They can only be used for your own purposes, as you cannot share them.

    If you want to create a public gist, make sure this option is deselected. Public gists are searchable, and they show up in Discover where people can browse newly appearing gists. Use public gists if you want other people to be able to find and see your code.

  5. If you want to create an anonymous gist, select the Anonymous option. Anonymous gists can be both public or private.
  6. If you want to open the newly created gist in your default browser, select the Open in browser option and click OK.

Jump to the GitHub version of a file

You can jump from the WebStorm to the GitHub version of a file. WebStorm detects which branch is currently active, and opens the GitHub copy of the selected file in the corresponding branch.

To view the remote copy of a file, select it in the editor or in the Project view, and choose Open on GitHub from the context menu of the selection. The remote version of the file in the current branch will open in the browser.

See Also

Last modified: 20 September 2017