Skip to content

Commit

Permalink
docs: initial readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
Brian Ryall committed Jan 22, 2024
1 parent 8408e07 commit 36091e6
Showing 1 changed file with 127 additions and 87 deletions.
214 changes: 127 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,75 +1,89 @@
# git-worktree.nvim<a name="git-worktreenvim"></a>

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).
<div align="center">

[![Lua](https://img.shields.io/badge/Lua-blue.svg?style=for-the-badge&logo=lua)](http://www.lua.org)
[![Neovim](https://img.shields.io/badge/Neovim%200.8+-green.svg?style=for-the-badge&logo=neovim)](https://neovim.io)

</div>

## TOC<a name="toc"></a>

<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=1 -->

- [git-worktree.nvim](#git-worktreenvim)
- [Known Issues](#known-issues)
- [Dependencies](#dependencies)
- [TOC](#toc)
- [About](#about)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [Setup](#setup)
- [Basic Setup](#basic-setup)
- [Telescope Config](#telescope-config)
- [Config](#config)
- [Usage](#usage)
- [Hooks](#hooks)
- [Save](#save)
- [Repository](#repository)
- [Options](#options)
- [Usage](#usage)
- [Telescope](#telescope)
- [Hooks](#hooks)
- [Made with fury](#made-with-fury)
- [Debugging](#debugging)
- [Troubleshooting](#troubleshooting)
- [Switch and Delete a worktrees](#switch-and-delete-a-worktrees)
- [Create a worktree](#create-a-worktree)

<!-- mdformat-toc end -->

## Known Issues<a name="known-issues"></a>
There are a few known issues. I'll try to be actively filing them in the issues. If you experience something, and it's not an issue, feel free to make an issue! Even if it's a dupe I am just happy for the contribution.
## About<a name="about"></a>

## Dependencies<a name="dependencies"></a>

Requires NeoVim 0.5+
Requires plenary.nvim
Optional telescope.nvim for telescope extension
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).

## Getting Started<a name="getting-started"></a>
## Installation<a name="installation"></a>

First, install the plugin the usual way you prefer.
- neovim 0.8.0+ required
- install using your favorite plugin manager
- or install using [lazy.nvim](https://github.com/folke/lazy.nvim)

```console
Plug 'ThePrimeagen/git-worktree.nvim'
```lua
{
"polarmutex/git-worktree.nvim",
branch = "v2",
dependencies = { "nvim-lua/plenary.nvim" }
}
```

Next, re-source your `vimrc`/`init.vim` and execute `PlugInstall` to ensure you have the plugin
installed.
- Optional: install telescope.nvim for telescope extension

## Setup<a name="setup"></a>
## Getting Started<a name="getting-started"></a>

## Repository<a name="repository"></a>
### Basic Setup<a name="basic-setup"></a>

This repository does work best with a bare repo. To clone a bare repo, do the following.
```lua
local gwt = require("git-worktree")
local Hooks = require("git-worktree.hooks")

```shell
git clone --bare <upstream>
-- REQUIRED
gwt:setup()
-- REQUIRED

-- you probably want al least this basic hook to change current buffer
-- on worktree switch, more on hook below
gwt:hooks({
SWITCH = Hooks.builtins.update_current_buffer_on_switch
})
```

If you do not use a bare repo, using telescope create command will be more helpful in the process of creating a branch.
### Telescope Config<a name="telescope-config"></a>

### 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.)
In order to use [Telescope](https://github.com/nvim-telescope/telescope.nvim) as a UI,
make sure to add `telescope` to your dependencies and paste this following snippet into your configuration.

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.
```lua
local gwt = require('git-worktree')
gwt:setup({})

### 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.
require('telescope').load_extension('git_worktree')
```
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/*"
```

## Options<a name="options"></a>
### Config<a name="config"></a>

`change_directory_command`: The vim command used to change to the new worktree directory.
Set this to `tcd` if you want to only change the `pwd` for the current vim Tab.
Expand All @@ -88,7 +102,8 @@ edit the wrong files.
`autopush`: When creating a new worktree, it will push the branch to the upstream then perform a `git rebase`

```lua
require("git-worktree").setup({
local gwt = require('git-worktree')
gwt:setup({
change_directory_command = <str> -- default: "cd",
update_on_change = <boolean> -- default: true,
update_on_change_command = <str> -- default: "e .",
Expand All @@ -97,7 +112,7 @@ require("git-worktree").setup({
})
```

## Usage<a name="usage"></a>
### Usage<a name="usage"></a>

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

Expand All @@ -106,55 +121,26 @@ The path can be either relative from the git root dir or absolute path to the wo
```lua
-- Creates a worktree. Requires the path, branch name, and the upstream
-- Example:
:lua require("git-worktree").create_worktree("feat-69", "master", "origin")
:lua require("git-worktree"):create_worktree("feat-69", "master", "origin")

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

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

## Telescope<a name="telescope"></a>

Add the following to your vimrc to load the telescope extension

```lua
require("telescope").load_extension("git_worktree")
```

### Switch and Delete a worktrees
To bring up the telescope window listing your workspaces run the following

```lua
:lua require('telescope').extensions.git_worktree.git_worktrees()
-- <Enter> - switches to that worktree
-- <c-d> - deletes that worktree
-- <c-f> - toggles forcing of the next deletion
:lua require("git-worktree"):delete_worktree("feat-69")
```

### Create a worktree
To bring up the telescope window to create a new worktree run the following

```lua
:lua require('telescope').extensions.git_worktree.create_git_worktree()
```
First a telescope git branch window 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 telescope create workflow, however if it finds a branch of the same name in the origin it will use it

## Hooks<a name="hooks"></a>
### Hooks<a name="hooks"></a>

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

```lua
local Worktree = require("git-worktree")
local gwt = require("git-worktree")

-- TODO Update
-- op = Operations.Switch, Operations.Create, Operations.Delete
-- metadata = table of useful values (structure dependent on op)
-- Switch
Expand All @@ -167,9 +153,9 @@ local Worktree = require("git-worktree")
-- Delete
-- path = path where worktree deleted

Worktree.on_tree_change(function(op, metadata)
if op == Worktree.Operations.Switch then
print("Switched from " .. metadata.prev_path .. " to " .. metadata.path)
gwt:hooks({
SWITCH = function(path, prev_path)
print("Switched from " .. prev_path .. " to " .. path)
end
end)
```
Expand All @@ -178,7 +164,61 @@ This means that you can use [harpoon](https://github.com/ThePrimeagen/harpoon)
or other plugins to perform follow up operations that will help in turbo
charging your development experience!

## Made with fury<a name="made-with-fury"></a>
## Save<a name="save"></a>

## Repository<a name="repository"></a>

This repository does work best with a bare repo. To clone a bare repo, do the following.

```shell
git clone --bare <upstream>
```

If you do not use a bare repo, using telescope create command will be more helpful in the process of creating a branch.

### Debugging<a name="debugging"></a>

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<a name="troubleshooting"></a>

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

All plugins are made live on [Twitch](https://twitch.tv/ThePrimeagen) with love
and fury. Come and join!
```
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
```

### Switch and Delete a worktrees<a name="switch-and-delete-a-worktrees"></a>

To bring up the telescope window listing your workspaces run the following

```lua
:lua require('telescope').extensions.git_worktree.git_worktrees()
-- <Enter> - switches to that worktree
-- <c-d> - deletes that worktree
-- <c-f> - toggles forcing of the next deletion
```

### Create a worktree<a name="create-a-worktree"></a>

To bring up the telescope window to create a new worktree run the following

```lua
:lua require('telescope').extensions.git_worktree.create_git_worktree()
```

First a telescope git branch window 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 telescope create workflow, however if it finds a branch of the same name in the origin it will use it

0 comments on commit 36091e6

Please sign in to comment.