Snacks picker documentation

[vitorf7]

I can see there was a PR to add snacks picker and I was wondering if there is any documentation on how to use the snacks picker to switch, create and delete worktrees as I have tried to find how to get it working but not worked yet?

[anir183]

@vitorf7

it seems like the snacks code was merged in the devel branch

i found some documentation in the origin of that pr

• https://github.com/ThePrimeagen/git-worktree.nvim/pull/136/changes#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5
• https://github.com/sk91/git-worktree.nvim/blob/snacks/README.md#snacks

Warning

Functionality seems broken and calling the function generates an error

Snacks

Switch and Delete a worktrees

To bring up the snacks picker listing your workspaces run the following

require("snacks-worktree").pick_git_worktree()
-- <Enter> - switches to that worktree
-- <c-d> - deletes that worktree
-- <c-f> - toggles forcing of the next deletion

Create a worktree

To bring up the snacks picker to create a new worktree run the following

require("snacks-worktree").create_worktree()

First a snacks git branch picker will appear. Pressing enter will choose the selected branch for the branch name. If no branch is selected, then the prompt will be used as the branch name.

After the git branch window, a prompt will be presented to enter the path name to write the worktree to.

As of now you can not specify the upstream in the snacks create workflow, however if it finds a branch of the same name in the origin it will use it

Lazy installation example

{
    "ThePrimeagen/git-worktree.nvim",
    dependencies = {
      "nvim-lua/plenary.nvim",
      "folke/snacks.nvim",
    },

    opts = {
      change_directory_command = "cd",
      update_on_change = true,
      update_on_change_command = "e .",
      clearjumps_on_change = true,
      autopush = false,
    },

    keys = {
      {
        "<leader>gws",
        function()
          require("snacks-worktree").pick_git_worktree()
        end,
        desc = "Pick Git Worktree",
      },
      {
        "<leader>gwc",
        function()
          require("snacks-worktree").create_worktree()
        end,
        desc = "Create Git Worktree",
      },
    },
  }

[polarmutex]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add Snacks picker documentation to the README

Current behavior:
Snacks picker support was merged into the devel branch (sourced from a fork at sk91/git-worktree.nvim), but there is no documentation in the README for how to configure or use it. Users have to dig through the PR history or third-party READMEs to find the API.

Desired behavior:
The README should have a Snacks section (alongside the existing Telescope section) that documents:

• The two entry point functions: require("snacks-worktree").pick_git_worktree() and require("snacks-worktree").create_worktree()
• The keybindings available in the picker (<Enter> to switch, <c-d> to delete, <c-f> to toggle force-delete)
• A complete Lazy plugin spec example showing dependencies (folke/snacks.nvim) and keymap setup
• Any known limitations (e.g. upstream cannot be specified in the create flow)

Key interfaces:

• The snacks-worktree Lua module (in devel branch) — read its public API to ensure docs match the actual implementation
• The README structure — follow the same format as the existing Telescope documentation section

Acceptance criteria:

• README has a Snacks section with the two public functions documented
• A complete Lazy config example is included and matches the actual module API
• Available picker keybindings are listed
• Known limitations are noted
• No changes to Snacks picker behavior or implementation (docs only)

Out of scope:

• Fixing any bugs in the Snacks picker implementation itself
• Merging devel into main
• Adding new Snacks picker functionality