Skip to content

VS Code IDE

Once Git and GitHub are configured, it's time to pick an editor that integrates the whole workflow into a single window. There are many excellent options:

In this guide we use VS Code because:

  • It's free and open source.
  • It has native Git integration (no plugins required).
  • It supports Markdown with live preview.
  • It runs on Windows, macOS, and Linux.
  • It has a huge ecosystem of extensions.

If Vim is your thing

Vim and Neovim are still first-class tools, especially on remote servers and for people who live in the terminal. There are configurations like LazyVim or AstroNvim that turn them into full IDEs. This guide doesn't cover them, but the choice is valid.

1. Installation

  1. Download the installer from code.visualstudio.com/Download.
  2. During installation, check these options:
  3. "Add to PATH" (adds code to your PATH so you can use it from the terminal).
  4. "Add 'Open with Code' action" (right-click in Explorer).
  5. When it finishes, open VS Code from the Start menu.

With Homebrew:

brew install --cask visual-studio-code

Or download the .dmg from the official site.

Debian/Ubuntu:

sudo apt install ./code_1.85.0-1702772538_amd64.deb

Fedora:

sudo dnf install code

Or from the official site (.deb, .rpm, and tarball available).

2. Initial configuration

Change the default shell

On Windows, the integrated terminal uses PowerShell by default. To use Git Bash (more comfortable with Unix commands):

  1. Open the Command Palette with Ctrl+Shift+P.
  2. Type Terminal: Select Default Profile.
  3. Choose Git Bash.

On macOS and Linux, the system shell is already Unix and works without changes.

Theme

VS Code ships with light and dark themes. To change:

  1. Ctrl+K followed by Ctrl+T (direct shortcut).
  2. Pick from the preinstalled themes or install a new one (below).

Font

For programmers, we recommend a font with programming ligatures:

  1. Install JetBrains Mono or Fira Code.
  2. In VS Code: Ctrl+, (Settings).
  3. Search for font family and set 'JetBrains Mono Ligatures', monospace.

3. Git integration

VS Code ships with Git integrated out of the box. If you have Git installed on your system, everything works without installing anything extra.

Source Control panel

The Source Control icon (the Git branch on the left sidebar) opens a panel where you can:

  • See modified, added, and deleted files.
  • Stage changes (+ button next to each file).
  • Write a commit message and confirm.
  • Push, pull, sync.
  • See and resolve conflicts visually.

Status bar

The status bar (bottom) shows:

  • The current branch (e.g. main, feature/login).
  • If there are pending changes (↓ for pull, ↑ for push, ⇅ for both).
  • The number of warnings and errors in the open file.

The Git Graph extension adds a visualization of the commit history with colors per branch. It's very useful for understanding merges and rebases.

Essential for Git/GitHub

Extension What it does
GitLens Annotates each line with author and date of the last commit.
GitHub Actions Highlighting and validation of YAML workflows.
GitHub Pull Requests Review and approve PRs without leaving the editor.

Essential for Markdown

Extension What it does
Markdown All in One Keyboard shortcuts, automatic TOC, enhanced preview.
markdownlint Real-time Markdown linter.
Mermaid Native preview of Mermaid diagrams.

Essential for productivity

Extension What it does
Error Lens Inline errors and warnings in code.
Project Manager Manage multiple repositories as projects.
Settings Sync Sync your configuration across machines.

Backup your configuration

In the cloud, VS Code automatically syncs your config if you sign in with GitHub (account icon, bottom left). It's the simplest way to have the same experience across all your machines.

5. Productive keyboard shortcuts

The most useful shortcuts for the Git/Markdown workflow:

Action Windows / Linux macOS
Command Palette Ctrl+Shift+P Cmd+Shift+P
Quick open (find file) Ctrl+P Cmd+P
Settings Ctrl+, Cmd+,
Toggle terminal Ctrl+` Ctrl+`
Markdown preview Ctrl+K + V Cmd+K + V
Format document Shift+Alt+F Shift+Option+F
Multi-cursor ++alt+click++ or Ctrl+Alt+Down ++option+click++ or Cmd+Option+Down
Move line up/down Alt+Up / Alt+Down Option+Up / Option+Down
Comment line Ctrl+/ Cmd+/
Go to definition F12 F12

Official cheat sheet

VS Code publishes a cheat sheet PDF with all shortcuts. Print it and keep it handy for the first few weeks.

6. Typical workflow

Let's see a real scenario: you're editing documentation, want to commit the changes, and open a PR.

Edit files

  1. Open the project folder (File → Open Folder or code . in terminal).
  2. Navigate the tree in the sidebar.
  3. Edit the files. The Source Control panel shows modified files in real time.

Review changes before committing

  1. Click a modified file from Source Control.
  2. VS Code opens an inline diff view: lines added in green, lines removed in red.
  3. Verify the changes are correct.

Commit

  1. In Source Control, type the message.
  2. Ctrl+Enter to confirm (or the ✓ button).
  3. If commit.gpgsign is enabled, the commit is signed automatically (see Signed commits with GPG).

Forcing signed commits from VS Code

Whether you commit from the integrated terminal or from VS Code's Source Control panel, signing is decided by Git, not the editor. So the global config is enough:

git config --global commit.gpgsign true
git config --global user.signingkey 5F2A8B3C9D4E1F6A
git config --global tag.gpgsign true

With commit.gpgsign true, every commit is signed: those made from the GUI panel and those made from the terminal. There is no separate VS Code option to "force signing only in the GUI"; the flag applies to all commits system-wide because it is a Git configuration, not an editor one.

Windows and the GPG path

On Windows with Git Bash, GPG is installed at C:\Program Files (x86)\GnuPG\bin\gpg.exe. If committing from VS Code shows gpg: failed to start... or cannot find gpg, set the path manually:

git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

Alternative: declare it in VS Code's settings.json so the editor uses that path without touching Git:

{
    "git.gpg": {
        "path": "C:/Program Files (x86)/GnuPG/bin/gpg.exe"
    }
}

Disable signing only in a specific project

If you want to sign commits in most repos but not in one particular project, use the flag without --global inside that project:

cd my-project-without-signing
git config commit.gpgsign false

Team-wide mandatory signing is enabled on GitHub through branch protection with "Require signed commits". See Signed commits with GPG for details.

Push and Pull Request

  1. After committing, a "Sync Changes" button appears in the status bar.
  2. Click it and choose Push.
  3. If you installed the GitHub Pull Requests extension, a "Create Pull Request" button appears that opens the GitHub web editor with the branch already selected.

7. Useful settings

Configure these options in settings.json (Ctrl+Shift+P → Preferences: Open User Settings (JSON)):

{
    "editor.fontFamily": "'JetBrains Mono', 'Fira Code', monospace",
    "editor.fontLigatures": true,
    "editor.formatOnSave": true,
    "editor.tabSize": 2,
    "editor.minimap.enabled": false,
    "editor.bracketPairColorization.enabled": true,
    "editor.guides.bracketPairs": true,
    "files.trimTrailingWhitespace": true,
    "files.insertFinalNewline": true,
    "git.autofetch": true,
    "git.confirmSync": false,
    "git.enableSmartCommit": true,
    "terminal.integrated.fontFamily": "'JetBrains Mono', monospace",
    "markdown.preview.fontSize": 14,
    "markdownlint.config": {
        "MD013": false,
        "MD033": false
    }
}

Version your settings.json

Store your settings.json in a dotfiles repository or sync with Settings Sync. That way you have the same experience on any machine.

Next step

With the IDE configured, you can move on to Markdown syntax to learn how to write the documentation content, or jump to Practice for full exercises.