How to use VS Code as your Git editor, difftool, and mergetool

15 Sep 2020

5 min read

Do you use VS Code as your default Git editor, or as your Git diff tool?

Should you?

Let’s look at the potential benefits of using VS Code as a fully-fledged Git partner, and how you can do it.

TLDR

To make VS Code your default “everything”, first you need to ensure you can run VS Code from the command-line as outlined in the Prerequisite section.

Then, run the command git config --global -e to edit the global config, and add the following:

[core]
  editor = code --wait
[diff]
  tool = vscode
[difftool "vscode"]
  cmd = code --wait --diff $LOCAL $REMOTE
[merge]
  tool = vscode
[mergetool "vscode"]
  cmd = code --wait $MERGED

If you want to see how an edit, diff, or merge looks in VS Code, go to the corresponding section to see screenshots.

Why should you make VS Code your default Git editor, diff tool, or merge tool?

It’s a personal choice! There are many, many options out there. Above all else, your tools should complement your workflow and not impede you.

I’ll explain my decision and maybe it will give your some insight in to understanding what works best for you. In a sentence, I prefer to do as much as I can in my code editor.

Here are the situations where I have encountered friction or have an alternate preference:

1. If I am executing an interactive git command that requires input from me to edit and review a chunk of text, I would prefer to stay in my code editor and stay in the same mental mode.
2. I haven’t used some of the Linux command-line tools associated with Git such as Nano enough to get the necessary muscle memory, I forget the commands! 🙈 It can be a flow-buster.
3. I prefer less switching between applications generally. I would prefer to switch to another tab of my code editor rather than a separate window.
4. For diffing, I prefer viewing it in a GUI-based editor.
5. Some merge conflicts are demanding, I like to jump to source files to get the complete picture, I can use familiar shortcuts if I can do it in VS Code.
6. If I can do it all in my code editor, I have a consistent colour theme without further configuration.

Prerequisite

You need to ensure you can run VS Code from the command-line before you can make it a default editor, diff tool, or merge tool. It is possible that this wasn’t done as part of your installation.

To test this, run the command code --help from the command line. If you did not see some help output, it means you currently can’t run VS Code from the command-line.

You can follow these steps to rectify that:

• Windows: You need to edit the Environment Variables, and add the location of your VS Code installation to the PATH variable. Or you could re-install and ensure that the it happens through the wizard (there is an option).
• macOS: Select Shell Command: Install 'Code' command in path from the Command Palette.
• Linux: Make sure you installed VS Code via a .deb or .rpm package.

Make VS Code your default editor

The default Git editor is Nano.

This is how Nano looks for a commit message.

This is how VS Code looks for a commit message.

Configuration

To update your git configuration, run the following command:

git config --global core.editor 'code --wait'

If you prefer that a new window opens each time, add the --new-window code flag:

git config --global core.editor 'code --wait --new-window'

If you only want to change it for your current project, run the same command without the –global git flag.

Unhappy and want to go back?

git config --global --unset core.editor

Make VS Code your default diff tool

The default diff tool is vimdiff.

Specifying a diff tool affects the git difftool command. The command git diff still performs diffing on the command-line. The difftool command starts an interactive dialogue with a queue of the affected files, asking you choose which files you wish open to open.

This is how vimdiff looks for a diff. Pass the 🕶!

This is how VS Code looks for a diff.

You will notice in the command-line in the screenshot above that my diff session shows 13 files that have changes. If the file list is long, you can cancel the process at whenever point you want the typical way: Ctrl + C. You will probably need to narrow down the scope of your command to make the set more manageable.

Configuration

To configure it from the command-line:

git config --global diff.tool vscode
git config --global difftool.vscode.cmd 'code --wait --diff $LOCAL $REMOTE'

This adds the following settings to your global Git config:

[diff]
	tool = vscode
[difftool "vscode"]
	cmd = code --wait --diff $LOCAL $REMOTE

You can paste this in yourself if you prefer.

If you’re not feeling VS Code as your diff tool, you run the command git difftool --tool-help to see more options.

Make VS Code your default merge tool

There is no default merge tool set.

When there is a conflict, you will get error messages when you try to pull or push changes. Running git mergetool will allow you to resolve conflicts.

Running vimdiff then looks like this:

This is what a merge conflict looks like in VS Code:

A CodeLens gives you options for resolving the conflict. If there is more than 1 conflict, a tool bar appears in the top right corner above the document giving you options to cycle through each conflict.

Configuration

To do it from the command-line:

git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

This adds the following settings to your global Git config:

[merge]
	tool = vscode
[mergetool "vscode"]
	cmd = code --wait $MERGED

You can paste this in yourself if you prefer.

If you’re not feeling VS Code as your merge tool, you run the command git mergetool --tool-help to see more options.

Conclusion

It’s simple to setup VS Code to manage all your git needs. It’s just a matter of preference if you want to use VS Code or stick with the command-line tools.

Happy coding! 🙂

Tagged

• vscode
• git