git-worktree.nvim: A Lua repository from polarmutex

A simple wrapper around git worktree operations, create, switch, and delete. There is some assumed workflow within this plugin, but pull requests are welcomed to fix that).

Quick Links

Prerequisites

Required

neovim >= 0.9
plenary.nvim

Optional

telescope.nvim

Installation

This plugin is available on LuaRocks:

{
  'polarmutex/git-worktree.nvim',
  version = '^2',
  dependencies = { "nvim-lua/plenary.nvim" }
}

Quick Setup

This plugin does not require to call setup function

Features

Usage

Three primary functions should cover your day-to-day.

The path can be either relative from the git root dir or absolute path to the worktree.

-- Creates a worktree.  Requires the path, branch name, and the upstream
-- Example:
require("git-worktree").create_worktree("feat-69", "master", "origin")

-- switches to an existing worktree.  Requires the path name
-- Example:
require("git-worktree").switch_worktree("feat-69")

-- deletes to an existing worktree.  Requires the path name
-- Example:
require("git-worktree").delete_worktree("feat-69")

Advanced Configuration

to modify the default configuration, set vim.g.git_worktree.

See :help git-worktree.config for a detailed documentation of all available configuration options.

vim.g.git_worktree = {
    ...
}

Hooks

Yes! The best part about git-worktree is that it emits information so that you can act on it.

local Hooks = require("git-worktree.hooks")

Hooks.register(Hooks.type.SWITCH, Hooks.builtins.update_current_buffer_on_switch)

Important

no builtins are registered by default and will have to be registered

This means that you can use harpoon or other plugins to perform follow up operations that will help in turbo charging your development experience!

Telescope Config

In order to use Telescope as a UI, make sure to add telescope to your dependencies and paste this following snippet into your configuration.

require('telescope').load_extension('git_worktree')

Debugging

git-worktree writes logs to a git-worktree-nvim.log file that resides in Neovim's cache path. (:echo stdpath("cache") to find where that is for you.)

By default, logging is enabled for warnings and above. This can be changed by setting vim.g.git_worktree_log_level variable to one of the following log levels: trace, debug, info, warn, error, or fatal. Note that this would have to be done before git-worktree's setup call. Alternatively, it can be more convenient to launch Neovim with an environment variable, e.g. > GIT_WORKTREE_NVIM_LOG=trace nvim. In case both, vim.g and an environment variable are used, the log level set by the environment variable overrules. Supplying an invalid log level defaults back to warnings.

Troubleshooting

If the upstream is not setup correctly when trying to pull or push, make sure the following command returns what is shown below. This seems to happen with the gitHub cli.

git config --get remote.origin.fetch

+refs/heads/*:refs/remotes/origin/*

if it does not run the following

git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"