narrow

narrow something

t9md

9,250

37

0.65.2

MIT

GitHub

This package provides the following services:

This package consumes the following services:

narrow

Build Status

narrow something.
Code navigation tool inspired by unite.vim, emacs-helm.
More information on wiki

narrow

What's this?

Roles in play.

overview

overview

control bar

control-bar

Bundled providers

You can check GIFs for all bundled provider here.
I use scan, search, git-diff-all, symbols in daily-basis, for other providers I don't use much.

Quick tour

To follow this quick-tour, you don't need custom keymap.

Step1. basic by using narrow:scan

  1. Open some text-editor, then via command-palette, invoke Narrow Scan.
  2. narrow-editor opened, Initial items are each lines on editor. As you type, you can narrow items.
  3. When you type apple as query. all apple matching items are listed.
  4. You can move normal up, down(or j, k in read-only mode) key to quick-preview items.
  5. enter to confirm. When confirmed, narrow-editor closed.

The read-only mode is enabled by default.

Step2. navigate from outside of narrow-editor.

  1. Open some text-editor, then via command-palette, invoke Narrow Scan.
  2. narrow-editor opened. As you type, you can narrow items.
  3. Click invoking editor. And see your clicked position is automatically reflected narrow-editor.
  4. ctrl-cmd-n to move to next-item, ctrl-cmd-p to move to previous-item.
  1. You can close narrow-editor by ctrl-g( no need to focus narrow-editor ).
  2. If you want to change narrow-query, you have to focus to narrow-editor
  1. These navigation keymaps are available for all provider(e.g. search, fold etc).

Step3. direct-edit

Direct-edit is "edit on narrow-editor then save to real-file" feature.
Available for following providers.

⚠️ This operation is dangerous, since you can update multiple files at once. ⚠️ You have to be careful enough to use this feature, don't use this without understanding what you are doing. ⚠️ I can say sorry, but I can not recover file for you.

  1. Open file from project, place cursor for variable name hello
  2. Then invoke Narrow Search By Current Word.
  3. All hello matching items are shows up on narrow-editor.
  4. If you want, you can further narrow by query.
  5. Then edit narrow-editor's text directly.
  1. Invoke Narrow Ui: Update Real File from command-palette.
  2. DONE, changes you made on narrow-editor items are applied to real-file(and saved).
  3. You can undo changes by re-edit items on narrow-editor and reapply changes by Narrow Ui: Update Real File.

Step4. [Experimental] search keyword by mouse

  1. Set Search.startByDoubleClick to true from settings-view.
  2. Double click keyword in editor.
  3. Each time you double click keyword, new narrow-editor open and old one is replaced.
  4. You can continue double click which ever narrow-editor or normal-editor.

Commands

Available in all text-editor

Other
Invoke narrow provide

No keymaps are provided

Available in narrow-editor(narrow-ui)

The !vmp followed by keymap means "which keymap is not available for vim-mode-plus user".
If you want use these keymap with vim-mode-plus, set it by yourself.
See Wiki

Keymaps

No keymap to invoke narrow provider(e.g narrow:scan).
Start it from command-palette or set keymap in keymap.cson.

⚠️ default keymap is not yet settled, this will likely to change in future version.

My keymap(vim-mode-plus user) and config

config.cson
  narrow:
    SelectFiles:
      rememberQuery: true
    confirmOnUpdateRealFile: false
keymap.cson

Explanation of my keymap.

# From outside of narrow-editor
# -------------------------

# `cmd-e` start `search-by-current-word` only when workspace does NOT have `narrow-editor`.
# NOTE: When workspace.has-narrow, `cmd-e` is mapped to `query-current-word` by default.
'atom-workspace:not(.has-narrow) atom-text-editor.vim-mode-plus:not(.insert-mode)':
  'cmd-e': 'narrow:search-by-current-word'

'atom-text-editor.vim-mode-plus:not(.insert-mode)':
  'ctrl-z':      'narrow:reopen'
  'space f':     'narrow:fold'
  'cmd-o':       'narrow:symbols-by-current-word'
  'cmd-shift-o': 'narrow:project-symbols-by-current-word'
  'cmd-r':       'narrow:symbols' # Override default cmd-r
  'cmd-shift-r': 'narrow:project-symbols' # Override default cmd-shift-r
  'space l':     'narrow:scan'
  'cmd-l':       'narrow:scan-by-current-word'
  'space s':     'narrow:search'
  'space G':     'narrow:git-diff-all'

# When workspace has narrow-editor
'atom-workspace.has-narrow atom-text-editor.vim-mode-plus.normal-mode':
  'cmd-f': 'narrow:focus' # focus to narrow-editor
  'cmd-i': 'narrow:focus-prompt' # focus to prompt of narrow-editor

  # Following three command have ctrl- prefixed by default to avoid conflicts.
  # But I don' care conflict, prefer more accessible keymap.
  'cmd-[': 'narrow:previous-query-history'
  'cmd-]': 'narrow:next-query-history'
  'cmd-e': 'narrow:query-current-word'

# narrow-editor regardless of mode of vim
'atom-text-editor.narrow.narrow-editor[data-grammar="source narrow"]':
  'cmd-f': 'narrow:focus'
  'cmd-i': 'narrow:focus-prompt' # cmd-i to return to calling editor.

  # Danger: apply change on narrow-editor to real file by `cmd-s`.
  'cmd-s': 'narrow-ui:update-real-file'

  # Move ui in between bottom dock and center workspace.
  'cmd-t': 'narrow-ui:relocate'

'atom-workspace.has-narrow atom-text-editor.vim-mode-plus.normal-mode,
  atom-workspace.has-narrow atom-text-editor.vim-mode-plus.visual-mode':
    'cmd-e': 'narrow:query-current-word' # set current word as query of active ui.

'atom-text-editor.narrow.narrow-editor.vim-mode-plus.normal-mode':
  'g g': 'narrow-ui:move-to-prompt'
  's': 'narrow-ui:select-files'
  ';': 'narrow-ui:confirm-keep-open'
  'n': 'narrow-ui:move-to-next-file-item'
  'p': 'narrow-ui:move-to-previous-file-item'

Recommended configuration for other packages.

"*":
  "autocomplete-plus":
    suppressActivationForEditorClasses: [
      # snip
      "narrow"
    ]
  # snip
  "vim-mode-plus":
    highlightSearchExcludeScopes: [
      "narrow"
    ]

Notes for vim-mode-plus user

⚠️ Limitation: for compatibility with vim-mode-plus.

Keymap

Learn keymap available as default.
e.g. You can move to next or previous item by tab, shift-tab(for this to work, you need vim-mode-plus v0.81.0 or later).

Start narrow from vim-mode-plus's search-input-form

If you are vim-mode-plus user. Following command are available from vim-mode-plus's search(/ or ?) mini-editor.

How to edit item-area for direct-edit.

Q&A

What providers are you seriously using?

In daily editing, I use.

scan, search, git-diff-all, symbols.

Why I'm not using others? reason is here.

Noticed I can close narrow-editor by normal cmd-w(core:close). Why I need narrow:close? What's the difference?

The biggest difference is narrow:close restore editor state(scrollTop, fold, active pane item) if user did only preview from startup.

Use whichever you want accordingly. I normally use narrow:close and occasionally use core:close such like when I want to focus next-pane-item of narrow-editor(so don't want to restore focus to narrow initiated editor).

How can I exclude particular file from narrow:search

Use backspace on item
Use select-files provider
  1. search editor by narrow:search, you see lots of editor mached items
  2. But you want exclude items in markdown file?
  1. You see items with items in markdown files are excluded.
  2. You can re-fine files to exclude by re-launching select-files.

Want to skip to next-file, previous-file

I want narrow:symbols always shows up at right-most pane and don't want to close.

  1. Open narrow:symbols( or maybe you want to use narrow:fold )
  2. Move this narrow-editor by drag and drop to the place where you want.
  3. From command-palette, execute Narrow Ui: Protect. Now narrow-editor protected.
  4. Protected narrow-editor is not closed by ctrl-g( narrow:close ), and not closed by confirm by enter.
  5. To close, use normal cmd-w or close button on tab.