fzf-checkout.txt

*fzf-checkout.txt*  Manage branches and tags with fzf
*fzf-checkout*

Author: Santos Gallegos <https://github.com/stsewd>
License: MIT
Repo: https://github.com/stsewd/fzf-checkout.vim

                              Type |gO| to see the table of contents (Neovim).

==============================================================================

FEATURES                                               *fzf-checkout-features*

- The current branch or commit will be show at the bottom
- The first item on the list will be the previous branch/tag
- Press <alt-enter> to track a remote branch locally (`origin/foo` becomes `foo`)
- Press <ctrl-b> to create a branch or tag with the current query as name
- Press <ctrl-d> to delete a branch or tag
- Press <ctrl-e> to merge a branch
- Press <ctrl-r> to rebase a branch
- Ask for confirmation for irreversible actions like delete
- Define your own actions

==============================================================================

COMMANDS                                               *fzf-checkout-commands*

                                                                  *:GBranches*
                                                     *fzf-checkout-:GBranches*
:GBranches [action] [filter]~

   Execute [action] over a list of all branches or filtered branches, if not
   action is given you can make use of keymaps to execute an action.

   List of available actions and their keymaps:

   - checkout: <enter>
   - track: <alt-enter>
   - create: <ctrl-b>
   - delete: <ctrl-d>
   - merge: <ctrl-e>
   - rebase: <ctrl-r>

   [filter] can be any of: `--all` (default), `--locals`, or `--remotes`.

                                                                      *:GTags*
                                                         *fzf-checkout-:GTags*
:GTags [action]~

   Execute [action] over a list of tags, if not action is given you can make
   use of keymaps to execute an action.

   List of available actions and their keymaps:

   - checkout: <enter>
   - create: <ctrl-b>
   - delete: <ctrl-d>

==============================================================================

SETTINGS                                               *fzf-checkout-settings*


If you have |fzf-vim| (https://github.com/junegunn/fzf.vim) installed,
this plugin will respect your |g:fzf_command_prefix| setting.

                                                      *g:fzf_checkout_git_bin*
g:fzf_checkout_git_bin~

Name of the `git` binary.

>
   let g:fzf_checkout_git_bin = 'git'
<
                                                  *g:fzf_checkout_git_options*
g:fzf_checkout_git_options~

additional options to pass to the `git` command.

>
   let g:fzf_checkout_git_options = ''
<

NOTE: It is not recommended to change the `--color` and `--format` parameters,
as they are used by the plugin and changing them may break something.

                                           *g:fzf_checkout_previous_ref_first*
g:fzf_checkout_previous_ref_first~

Display previously used branch first independent of specified sorting.

>
   let g:fzf_checkout_previous_ref_first = v:true
<
                                                    *g:fzf_checkout_view_mode*
g:fzf_checkout_view_mode~

Predefined styles for displaying branches and tags.
Values can be:

- `inline`: Show the tag/branch information in the list only.
- `preview`: Show the tag/branch information in the preview window only.
- `inline+preview`: Show the tag/branch information in the list and preview window.
- `auto`: Use `inline` or `inline+preview` depending of the width of the window.

>
   let g:fzf_checkout_view_mode = 'auto'
<
                                                    *g:fzf_checkout_show_help*
g:fzf_checkout_show_help~

Show available keymaps.

>
   let g:fzf_checkout_show_help = v:true
<

                                                        *g:fzf_branch_actions*
g:fzf_branch_actions~

A dictionary of actions for branches. The keys are the name of the action,
and the value is a dictionary with the following keys:

- `prompt`: A string to use it as prompt when executing this action
- `execute`: A string to be executed when performing this action.
  You can make use of the following placeholders:
  - `{git}`: Replaced with the value from |g:fzf_checkout_git_bin|
  - `{cwd}`: Replaced, if |g:fzf_checkout_use_current_buf_cwd| is enabled, with
    the directory from the current buffer or the current working directory.
  - `{branch}`: Replaced with the branches selected
  - `{tag}`: Replaced with the tags selected
  - `{input}`: Replaced with the input from the user
- `execute`: A function reference with `git`, `branch`/`tag`, `input` as arguments.
- `multiple`: The action supports multiple selections?
- `keymap`: The keymap used to execute this action (can be empty)
- `required`: A list of required elements (`['branch', 'tag', 'input']`) to perform this action
- `confirm`: Ask for confirmation before executing this action?

>
   let g:fzf_branch_actions = {
         \ 'checkout': {
         \   'prompt': 'Checkout> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} checkout {branch}']),
         \   'multiple': v:false,
         \   'keymap': 'enter',
         \   'required': ['branch'],
         \   'confirm': v:false,
         \ },
         \ 'track': {
         \   'prompt': 'Track> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} checkout --track {branch}']),
         \   'multiple': v:false,
         \   'keymap': 'alt-enter',
         \   'required': ['branch'],
         \   'confirm': v:false,
         \ },
         \ 'create': {
         \   'prompt': 'Create> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} checkout -b {input}']),
         \   'multiple': v:false,
         \   'keymap': 'ctrl-b',
         \   'required': ['input'],
         \   'confirm': v:false,
         \ },
         \ 'delete': {
         \   'prompt': 'Delete> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} branch -D {branch}']),
         \   'multiple': v:true,
         \   'keymap': 'ctrl-d',
         \   'required': ['branch'],
         \   'confirm': v:true,
         \ },
         \ 'merge':{
         \   'prompt': 'Merge> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} merge {branch}']),
         \   'multiple': v:false,
         \   'keymap': 'ctrl-e',
         \   'required': ['branch'],
         \   'confirm': v:true,
         \ },
         \ 'rebase':{
         \   'prompt': 'Rebase> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} rebase {branch}']),
         \   'multiple': v:false,
         \   'keymap': 'ctrl-r',
         \   'required': ['branch'],
         \   'confirm': v:true,
         \ },
         \}
<

                                                           *g:fzf_tag_actions*
g:fzf_tag_actions~

Same as |g:fzf_branch_actions|, but used to define tag actions.

>
   let g:fzf_tag_actions = {
         \ 'checkout': {
         \   'prompt': 'Checkout> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} checkout {tag}']),
         \   'multiple': v:false,
         \   'keymap': 'enter',
         \   'required': ['tag'],
         \   'confirm': v:false,
         \ },
         \ 'create': {
         \   'prompt': 'Create> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} tag {input}']),
         \   'multiple': v:false,
         \   'keymap': 'ctrl-b',
         \   'required': ['input'],
         \   'confirm': v:false,
         \ },
         \ 'delete': {
         \   'prompt': 'Delete> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} tag -d {tag}']),
         \   'multiple': v:true,
         \   'keymap': 'ctrl-d',
         \   'required': ['tag'],
         \   'confirm': v:true,
         \ },
         \}
<

                                               *g:fzf_checkout_merge_settings*
g:fzf_checkout_merge_settings~

Set it to `v:true` if you want to override some options from
|g:fzf_branch_actions| or |g:fzf_tag_actions|.
Set it to `v:false` if you want to have full control over the defined actions.

>
   let g:fzf_checkout_merge_settings= v:true
<
                                          *g:fzf_checkout_use_current_buf_cwd*
g:fzf_checkout_use_current_buf_cwd~

If true, set the `{cwd}` placeholder to the directory from the current buffer.
Useful when working in a multi-git-repository project (with submodules for example).
This option is disable by default.

>
   let g:fzf_checkout_use_current_buf_cwd = v:false
<

                                                  *g:fzf_checkout_preview_cmd*
g:fzf_checkout_preview_cmd~

Preview command to use in fzf's `--preview` option.
You can make use of the following placeholders:

- `{git}`: Replaced with the value from |g:fzf_checkout_git_bin|
- `{cwd}`: Replaced, if |g:fzf_checkout_use_current_buf_cwd| is enabled, with
  the directory from the current buffer or the current working directory.

>
   let g:fzf_checkout_preview_cmd = '{git} -C {cwd} show --color=always {1} --'
>

==============================================================================

FUNCTIONS                                             *fzf-checkout-functions*

                                                          *fzf_checkout#run()*
fzf_checkout#run({command}, {...})

When using Noevim, executes a command asynchronously and shows its result using
|nvim_notify()|. When using Vim it executes the command using |execute()| and
prints its result. The command can have the same placeholders documented at
|g:fzf_branch_actions|.

This function is mainly used in the `execute` key of the
|g:fzf_branch_actions| and |g:fzf_tag_actions| settings as a partial function,
for example:

>
   let g:fzf_branch_actions = {
         \ 'checkout': {
         \   'prompt': 'Checkout> ',
         \   'execute': function('fzf_checkout#run', ['{git} -C {cwd} checkout {branch}']),
         \   'multiple': v:false,
         \   'keymap': 'enter',
         \   'required': ['branch'],
         \   'confirm': v:false,
         \}}
<

vim:tw=78:ts=8:ft=help:norl: