Skip to content

Latest commit

 

History

History
194 lines (140 loc) · 5.96 KB

README.md

File metadata and controls

194 lines (140 loc) · 5.96 KB

✨ scratch-buffer.vim ✨

🚀 No more hassle with file paths! The fastest way to open an instant scratch buffer.

For Vim/Neovim.

This Vim plugin is created by Cline (Roo Code) and me!

Table of Contents

🔧 Quick Start

:ScratchBufferOpen  " Open a temporary buffer using default options
:ScratchBufferOpen md sp 5  " Open a temporary Markdown buffer with :sp and height 5
:ScratchBufferOpenFile ts vsp 100  " Open a persistent TypeScript buffer with :vsp and width 100
:ScratchBufferOpenNext  " Open next temporary buffer
:ScratchBufferOpenFileNext  " Open next persistent buffer

Please see 'Detailed Usage' section for more information.

🔥 Why scratch-buffer.vim?

  • Open instantly! Just run :ScratchBufferOpen!
  • No file management! Perfect for quick notes and testing code snippets.
  • Works anywhere! Whether in terminal Vim or GUI, it's always at your fingertips.

⚡ Supercharge with vim-quickrun!

💡 Combine it with vim-quickrun to execute code instantly!

" Write TypeScript code...
:ScratchBufferOpen ts

" ...and run it immediately!
:QuickRun

⚖️ Comparison with scratch.vim

scratch.vim is a great plugin. However, vim-scratch-buffer adds more features.

Compared to scratch.vim, vim-scratch-buffer provides these additional features:

  • Flexible buffer management

    • Open multiple buffers with sequential numbering (:ScratchBufferOpenNext)
    • Quick access to recently used buffers (:ScratchBufferOpen)
    • When you want to take notes on different topics, scratch.vim only allows one buffer
    • See :help :ScratchBufferOpen and :help :ScratchBufferOpenNext

  • Buffer type options

    • Choose between writeable buffers or temporary buffers
    • Automatic saving for file buffers when enabled
    • Convert temporary buffers to persistent ones when needed
    • See :help :ScratchBufferOpen and :help :ScratchBufferOpenFile

  • Customization options

    • Specify filetype for syntax highlighting, for :QuickRun, and for etc
    • Choose opening method (:split or :vsplit)
    • Control buffer height/width
    • Configurable auto-hiding behavior: scratch.vim compatibility
    • Customize buffer file locations: 
      " Configure different paths for temporary and persistent buffers
let g:scratch_buffer_file_pattern = #{
  \ when_tmp_buffer: '/tmp/scratch-tmp-%d',      " For :ScratchBufferOpen
  \ when_file_buffer: expand('~/scratch/%d'),    " For :ScratchBufferOpenFile
\ }
" This is useful if you want to keep a file buffer directory
" (`~/tmp` in the above case) with `.prettier`, etc.

Please also see doc/vim-scratch-buffer.txt for other functions.

⚙️ Detailed Usage

" Basic Usage

" Open a temporary buffer using default settings
:ScratchBufferOpen

" Same as :ScratchBufferOpen but opens a writable persistent buffer
:ScratchBufferOpenFile
" Open a new scratch buffer with a specific filetype

" Example: Markdown
:ScratchBufferOpen md

" Example: TypeScript
:ScratchBufferOpen ts

" Example: No filetype
:ScratchBufferOpen --no-file-ext
" Open multiple scratch buffers
:ScratchBufferOpen md      " Opens most recently used buffer
:ScratchBufferOpenNext md  " Always creates a new buffer
" Open a small buffer at the top for quick notes
:ScratchBufferOpen md sp 5
:ScratchBufferOpen --no-file-ext sp 5
" Delete all scratch files and buffers
:ScratchBufferClean

Please also see doc/vim-scratch-buffer.txt for other usage.

⌨️ Default Keymappings

When g:scratch_buffer_use_default_keymappings is enabled (default: v:false), the following keymappings are available:

" Quick open commands (execute immediately)
nnoremap <silent> <leader>b <Cmd>ScratchBufferOpen<CR>
nnoremap <silent> <leader>B <Cmd>ScratchBufferOpenFile<CR>

" Interactive commands (allows adding arguments)
nnoremap <leader><leader>b :<C-u>ScratchBufferOpen<Space>
nnoremap <leader><leader>B :<C-u>ScratchBufferOpenFile<Space>

The quick open commands create buffers with default settings, while the interactive commands let you specify file extension, open method, and buffer size.

You can customize these mappings by disabling the defaults:

let g:scratch_buffer_use_default_keymappings = v:false

And then defining your own:

" Example custom mappings
nnoremap <silent> <leader>s <Cmd>ScratchBufferOpen<CR>
nnoremap <silent> <leader>S <Cmd>ScratchBufferOpenFile<CR>

✨ scratch.vim compatibility

To make the plugin behave like scratch.vim, you can enable automatic buffer hiding! When enabled, scratch buffers will automatically hide when you leave the window. You can configure this behavior separately for temporary buffers and file buffers.

Enable both types of buffer hiding with:

let g:scratch_buffer_auto_hide_buffer = #{
  \ when_tmp_buffer: v:true,
  \ when_file_buffer: v:true,
\ }

Or enable hiding for only temporary buffers:

let g:scratch_buffer_auto_hide_buffer = #{ when_tmp_buffer: v:true }

Or enable hiding for only file buffers:

let g:scratch_buffer_auto_hide_buffer = #{ when_file_buffer: v:true }