WebStorm Git Integration: Complete Guide

Introduction to WebStorm Git Integration

WebStorm, JetBrains' powerful IDE for JavaScript and TypeScript development, ships with a first-class Git integration that eliminates the need to constantly switch between your editor and terminal. Whether you're working on a solo project or collaborating with a large team, WebStorm's Git tooling provides visual diffs, interactive rebases, conflict resolution tools, and much more—all accessible without leaving your editor.

What Is WebStorm Git Integration?

WebStorm Git Integration is a built-in version control system (VCS) layer that wraps Git commands into a graphical interface. It exposes Git functionality through tool windows, context menus, keyboard shortcuts, and dedicated dialogs. The integration supports all major Git workflows including branching, merging, rebasing, cherry-picking, stashing, and submodule management.

Why It Matters

Using Git through WebStorm offers several advantages over a purely command-line workflow:

• Visual diffs: Side-by-side comparisons with syntax highlighting make reviewing changes faster and more accurate.
• Reduced context switching: Commit, push, pull, and resolve conflicts without leaving your code.
• Safety nets: Local history and shelf features provide recovery options beyond standard Git.
• Streamlined code review: Inline blame annotations and change markers help you understand the evolution of your codebase.
• Conflict resolution: A three-way merge visualizer simplifies resolving even complex merge conflicts.

Setting Up Git in WebStorm

Prerequisites

Before configuring Git in WebStorm, ensure Git is installed on your system. You can verify this by running:

git --version

If Git is not installed, download it from the official website or install it via your package manager:

# macOS
brew install git

# Ubuntu/Debian
sudo apt install git

# Windows (winget)
winget install Git.Git

Configuring the Git Executable

To link Git with WebStorm, navigate to Preferences/Settings > Version Control > Git. WebStorm usually auto-detects the Git executable, but you can specify the path manually. Click the Test button to confirm the configuration is correct.

You should also configure your global Git identity if you haven't already:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Cloning a Repository

To clone an existing repository into WebStorm, go to File > New > Project from Version Control or use the welcome screen's Get from VCS button. Enter the repository URL and the local destination path:

# Example repository URL
https://github.com/your-org/your-repo.git

WebStorm will clone the repository and open it as a new project, automatically initializing the Git integration.

Initializing a New Repository

If you're starting a new project, you can initialize Git directly from WebStorm by selecting VCS > Enable Version Control Integration and choosing Git from the dropdown. Alternatively, use the terminal:

git init
git add .
git commit -m "Initial commit"

Core Git Operations in WebStorm

Viewing Changes

The Commit tool window (formerly the Changes view) displays all modified, added, and deleted files. Files are grouped by changelist, allowing you to organize related changes. Gutter markers in the editor also indicate added, modified, or deleted lines with color-coded stripes—green for additions, blue for modifications, and grey for deletions.

To view a detailed diff of any file, double-click it in the Commit tool window or press Ctrl+D (Windows/Linux) or Cmd+D (macOS).

Staging and Committing

WebStorm uses a changelist-based staging model. By default, all modified files appear in the Default changelist. You can create custom changelists to group related changes:

1. Right-click a file in the Commit tool window.
2. Select Move to Another Changelist.
3. Create a new changelist or select an existing one.

To commit changes, press Ctrl+K (Windows/Linux) or Cmd+K (macOS) to open the Commit dialog. Here you can:

• Select which files to include.
• Write a commit message.
• Run pre-commit checks like code inspection or formatting.
• Amend the previous commit if needed.

A well-structured commit message follows the conventional commits format:

feat(auth): add OAuth2 login flow

- Implement token refresh logic
- Add login callback handler
- Update auth context provider

Pushing and Pulling

After committing, push your changes to the remote repository using Ctrl+Shift+K (Windows/Linux) or Cmd+Shift+K (macOS). The Push dialog shows the commits to be pushed and allows you to review them before sending.

To pull changes from the remote, use Git > Pull or Ctrl+T (Windows/Linux) / Cmd+T (macOS). You can choose between merge and rebase strategies in the pull dialog.

Branch Management

Creating and Switching Branches

WebStorm's branch management is accessible from the status bar in the bottom-right corner. Click the branch name to open the branches popup, where you can:

• Create a new branch from the current HEAD or any existing branch/tag.
• Switch to an existing local or remote branch.
• Rename or delete branches.
• Compare branches to see divergent commits.

For a feature-based workflow, create branches with descriptive names:

feature/user-profile-page
bugfix/login-redirect-loop
hotfix/security-patch-xss
release/v2.1.0

Merging Branches

To merge a branch into your current branch, open the branches popup, select the target branch, and choose Merge into Current. WebStorm will perform the merge and alert you if conflicts arise.

Rebasing

WebStorm supports both standard and interactive rebases. To rebase your current branch onto another branch, select it in the branches popup and choose Rebase Current onto Selected.

For interactive rebasing, use Git > Rebase and select the base commit. The interactive rebase dialog lets you:

• Pick: Keep the commit as-is.
• Squash: Combine the commit with the previous one.
• Fixup: Combine and discard the commit message.
• Reword: Change the commit message.
• Drop: Remove the commit entirely.

Resolving Merge Conflicts

When Git cannot automatically merge changes, WebStorm launches its conflict resolution tool. The three-way merge editor displays three panes:

• Left pane: Your local changes.
• Center pane: The merge result (editable).
• Right pane: The incoming changes from the remote.

Conflicts are highlighted with red markers. Use the >> and << buttons to accept changes from either side, or manually edit the center pane to combine changes. Once all conflicts are resolved, click Apply and continue the merge.

Here's an example of a conflict marker you might see in a raw file:

<<<<<<< HEAD
function getUser(id) {
  return fetch(`/api/users/${id}`);
}
=======
function getUser(id) {
  return fetch(`/api/v2/users/${id}`).then(res => res.json());
}
>>>>>>> feature/api-v2

Using WebStorm's visual resolver, you can accept the left version, the right version, or merge both into a final result without manually editing these markers.

Stashing and Shelving Changes

Git Stash

Stashing allows you to temporarily save uncommitted changes and restore them later. In WebStorm, access stashing via Git > Uncommitted Changes > Stash Changes. You can later apply or pop the stash from the same menu.

# Equivalent CLI commands
git stash push -m "work in progress on dashboard"
git stash list
git stash pop

WebStorm Shelves

Shelving is a WebStorm-specific feature similar to stashing but stored within the IDE. Shelves are useful when you want to save changes without affecting Git's stash list. Access shelving via Git > Uncommitted Changes > Shelve Changes.

Key differences between stash and shelf:

• Stash: Managed by Git, accessible from any Git client.
• Shelf: Managed by WebStorm, IDE-specific, supports unshelving with conflict detection.

Working with Pull Requests

WebStorm integrates with GitHub, GitLab, and Bitbucket, allowing you to create, review, and merge pull requests directly from the IDE. To use this feature:

1. Navigate to Preferences/Settings > Version Control > GitHub (or GitLab/Bitbucket).
2. Add your account using a token or OAuth authentication.
3. Open the Pull Requests tool window.

From the Pull Requests tool window, you can:

• Create new PRs with automatically populated branch and title information.
• View diffs of all changed files in a PR.
• Add review comments inline.
• Merge or close PRs without leaving the IDE.

Using Git Annotations and History

Blame Annotations

To see who last modified each line of a file, right-click in the editor gutter and select Annotate with Git Blame. This displays the author, commit hash, and date next to each line. Clicking an annotation opens the corresponding commit details.

Git History

The Git History tab shows the full commit log for the current branch or selected file. You can filter by author, date, branch, or text. Right-clicking a commit provides options to cherry-pick, revert, or create a branch from it.

Comparing Versions

To compare a file's current version with a previous commit, right-click the file and select Git > Compare with Revision. Choose the commit to compare against, and WebStorm displays a visual diff.

Best Practices

Write Meaningful Commit Messages

Use the conventional commits standard for consistency across your team. WebStorm can enforce commit message templates by configuring them in Preferences/Settings > Version Control > Commit.

Commit Frequently with Logical Groupings

Use WebStorm's changelists to group related changes and commit them separately. This keeps your history clean and makes it easier to revert specific changes if needed.

Leverage Pre-Commit Hooks

WebStorm can run inspections and formatting before each commit. Enable these in the Commit dialog by checking options like Reformat code, Rearrange code, and Optimize imports. For more robust automation, use tools like Husky:

// package.json
{
  "scripts": {
    "prepare": "husky install"
  },
  "devDependencies": {
    "husky": "^8.0.0",
    "lint-staged": "^13.0.0"
  }
}

# .husky/pre-commit
npx lint-staged

// lint-staged.config.js
module.exports = {
  "*.js": ["eslint --fix", "prettier --write"],
  "*.css": ["stylelint --fix", "prettier --write"]
};

Use .gitignore Effectively

WebStorm can automatically add files to .gitignore when you select Ignore from the Commit tool window context menu. A typical Node.js project's .gitignore includes:

# Dependencies
node_modules/

# Build output
dist/
build/

# Environment variables
.env
.env.local

# IDE files
.idea/

# Logs
*.log
npm-debug.log*

# OS files
.DS_Store
Thumbs.db

Regularly Pull and Rebase

To avoid large merge conflicts, pull changes frequently and prefer rebasing over merging when working on long-lived feature branches. WebStorm's pull dialog makes it easy to switch between merge and rebase strategies.

Review Changes Before Committing

Always review your changes in the Commit dialog before finalizing. Use the diff viewer to catch debugging code, console statements, or accidental changes that shouldn't be committed.

Useful Keyboard Shortcuts

• Ctrl+K / Cmd+K — Commit changes
• Ctrl+Shift+K / Cmd+Shift+K — Push changes
• Ctrl+T / Cmd+T — Pull / Update project
• Ctrl+D / Cmd+D — Show diff for selected file
• Alt+` — Open the VCS operations quick menu
• Ctrl+Shift+G / Cmd+Shift+G — Show selection history

Conclusion

WebStorm's Git integration transforms version control from a terminal chore into a seamless part of your development workflow. By leveraging visual diffs, interactive rebasing, conflict resolution tools, and pull request management, you can work faster and with fewer errors. The key to getting the most out of these features is consistency—adopt a clear branching strategy, write meaningful commit messages, and take advantage of WebStorm's changelists and pre-commit inspections to keep your codebase clean. Whether you're a solo developer or part of a large team, mastering WebStorm's Git tooling will make you a more efficient and confident developer.