• Stars
    star
    110
  • Rank 309,408 (Top 7 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created about 8 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

narrow something

narrow

Build Status

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

narrow

What's this?

  • Provide narrowing UI like emacs-helm and unite/denite.vim.
  • Not aiming to become "can open anything from narrow-able UI" package.
  • Primal focus is on code-navigation.
  • Provider provide items( e.g. by search files in project ), you can filter items by query to narrow down further.
  • As you move cursor on active-editor, current item on narrow-ui is automatically synced.
  • You no longer lost like "Where am I?" when you are working on multiple files.
  • Let narrow navigate to next/previous item to aid your concentration.
  • Edit with confidence for no-overlook by direct-edit( edit on ag search result on narrow-editor then apply changes to real-file ).
  • In mind
    • keyboard navigation.
    • vim-mode-plus integration( I'm also maintainer of vim-mode-plus ).
  • Also see UseCase on wiki and Q&A on this doc

Roles in play.

  • narrow-editor or narrow-ui: filter items by query and render items.
  • narrow-provider: Provide items to narrow.

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.

  • scan: Scan current editor.
  • search: Search by ag( you need to install ag by yourself).
  • atom-scan: Similar to search but use Atom's atom.workspace.scan.
  • fold: Provide fold-starting rows as item.
  • git-diff-all: Show all modified state file across project.
  • symbols: Provide symbols for current file.
  • project-symbols: Provide project-wide symbols information by reading tags file.

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.
  • If you are vim-mode-plus user, You can use tab and shift-tab.
  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
  • Use ctrl-cmd-f( narrow:focus ) to focus narrow-editor.
  • Use ctrl-cmd-i( narrow:focus-prompt ) to directly focus narrow-editor's query prompt row.
  • Both commands are available from outside/inside of 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.

  • scan
  • search
  • atom-scan

⚠️ 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.
  • Place cursor on hello. Then ctrl-cmd-g(find-and-replace:select-all), then type world.
  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
  • narrow:focus: ( ctrl-cmd-f ) Focus to narrow-editor, if executed in narrow-editor, it re-focus to original editor.
  • narrow:focus-prompt: ( ctrl-cmd-i ) Focus to narrow-editor's query input prompt, if executed in narrow-editor, it re-focus to original editor.
  • narrow:refresh: Manually refresh items in narrow-editor.
  • narrow:close: ( ctrl-g ) Close currently opened narrow-editor one at a time.
  • narrow:next-item: ( ctrl-cmd-n ) Move cursor to position of next-item.
  • narrow:previous-item: ( ctrl-cmd-p ) Move cursor to position of previous-item.
  • narrow:reopen: ( no default keymap ) Reopen closed narrow editor up to 10 recent closed.
  • narrow:query-current-word: ( ctrl-cmd-e ) Replace active narrow-editor's query with cursor word.
  • narrow:previous-query-history: ( ctrl-cmd-[ ) Replace active narrow-editor's query with previous history entry.
  • narrow:next-query-history: ( ctrl-cmd-] ) Replace active narrow-editor's query with next history entry.
Invoke narrow provide

No keymaps are provided

  • narrow:scan
  • narrow:scan-by-current-word
  • narrow:fold
  • narrow:fold-by-current-word
  • narrow:search: ag search. need install by your self.
  • narrow:search-by-current-word
  • narrow:search-current-project
  • narrow:search-current-project-by-current-word
  • narrow:atom-scan
  • narrow:atom-scan-by-current-word
  • narrow:symbols
  • narrow:symbols-by-current-word
  • narrow:project-symbols:
  • narrow:project-symbols-by-current-word:
  • narrow:git-diff-all

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

  • core:confirm: ( enter ) Close narrow-editor
  • narrow-ui:confirm-keep-open: keep open narrow-editor
  • narrow-ui:open-here: Open item at same pane of UI's pane.
  • narrow-ui:preview-item: Preview currently selected item manually( you don't need in most case ).
  • narrow-ui:preview-next-item: ( tab ) Preview next-item without moving cursor from narrow-editor's query prompt.
  • narrow-ui:preview-previous-item: ( shift-tab ) Preview next-item without moving cursor from narrow-editor's query prompt.
  • narrow-ui:toggle-auto-preview: ( ctrl-r for non-vim-mode-plus user) Disable/enable auto-preview for this narrow-editor.
  • narrow-ui:move-to-prompt: ctrl-cmd-i
  • narrow-ui:stop-insert: escape
  • narrow-ui:update-real-file: Apply changes made in narrow-editor to real-file.( edit in narrow-editor then save it to real file. )
  • narrow-ui:protect: No keymap by default, Protect narrow-editor from being destroyed by narrow:close( ctrl-g ).
  • narrow-ui:exclude-file: backspace, Exclude items which matches filePath of currently selected item's.
  • narrow-ui:clear-excluded-files: ctrl-backspace, Clear excluded files list.
  • narrow-ui:select-files: cmd-backspace, interactively select which filePath's items to appear on narrow-editor.
  • narrow-ui:toggle-search-whole-word: alt-cmd-w
  • narrow-ui:toggle-search-ignore-case: alt-cmd-c
  • narrow-ui:toggle-search-use-regex: alt-cmd-/
  • narrow-ui:start-insert: I(!vmp), a(!vmp)
  • narrow-ui:move-to-next-file-item: n(!vmp)
  • narrow-ui:move-to-previous-file-item: p(!vmp)
  • narrow-ui:relocate: No keymap by default, Switch location where ui opened between center workspace and bottom dock.

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.

  • cmd-f: To focus to narrow-editor AND focus-back to original-editor
  • cmd-i: To focus to narrow-editor's prompt AND focus-back to original-editor
  • cmd-e:
    • When workspace has no narrow-edior on workspace: start narrow:search-by-current-word.
    • When workspace has at least one narrow-edior: query-current-word( by default keymap).
      • Replace active narrow-edior's query with cursor-word.
  • cmd-[: narrow:previous-query-history Recall previous history
  • cmd-]: narrow:next-query-history, Recall next history
  • ctrl-g: Close narrow-editor from wherever.
  • tab, shift-tab: to move to next/previous item.
  • ;: confirm current-item without closing narrow-editor, I can close narrow-editor by ctrl-g.
# 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.

  • Suppress autocomplete-plus's popup on narrow-editor
  • Disable vim-mode-plus's highlight-search on narrow-editor
"*":
  "autocomplete-plus":
    suppressActivationForEditorClasses: [
      # snip
      "narrow"
    ]
  # snip
  "vim-mode-plus":
    highlightSearchExcludeScopes: [
      "narrow"
    ]

Notes for vim-mode-plus user

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

  • If you use atom v1.16.0 or older,
    • Don't enable vim-mode-plus.automaticallyEscapeInsertModeOnActivePaneItemChange
    • If you enabled, each query input on narrow-editor of search provider cause mode-change from insert-mode to normal-mode.
  • If you use atom v1.17.0 or older( currently in beta ).
    • This limitation is no longer exists.

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.

  • vim-mode-plus-user:narrow:scan
  • vim-mode-plus-user:narrow:search
  • vim-mode-plus-user:narrow:search-current-project
  • vim-mode-plus-user:narrow:atom-scan

How to edit item-area for direct-edit.

  • In narrow-editor, i, a in normal-mode move cursor to prompt line.
  • So when you want to edit items itself for direct-edit and update-real-file use other key to enter insert-mode.
  • I is intentionally mapped to vim-mode-plus:activate-insert-mode which is normally mapped to i.
    • Which might not be intuitive, but I want make item mutatation bit difficult. So user have to type I.
  • Other than I, you can start insert-mode by A, c etc..

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.

  • fold: Since it similar to symbols.
  • atom-scan: it is provided for windows user who can't use search(need ag or rg).

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.

  • narrow:close: Close narrow-editor and restore editor state when it appropriate. Also can close narrow-editor regardless of current active-editor.
  • core:close: Just destroy narrow-editor.

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 backspace to exclude particular file from result.
  • ctrl-backspace clear excluded file list and refresh
  • These keymaps are available in narrow-editor and you are in read-only-mode
Use select-files provider
  • You can launch select-files by cmd-backspace or clicking folder-icon on control-bar.
  1. search editor by narrow:search, you see lots of editor mached items
  2. But you want exclude items in markdown file?
  • launch select-files, all file paths are listed as item.
  • Then type md on query, you see markdown filepath that macheed md.
  • Then add !, now your query is md!, this is treated as all files not matching md.
  • enter to confirm.
  1. You see items with items in markdown files are excluded.
  2. You can re-fine files to exclude by re-launching select-files.
  • e.g. To exclude spec folder, you can add spec/! as query.
  • e.g. To include .js file only, you can set query to .js.

Want to skip to next-file, previous-file

  • Use n, p in read-only mode.

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.

More Repositories

1

atom-vim-mode-plus

vim-mode improved
CoffeeScript
1,404
star
2

vim-choosewin

Land on window you chose like tmux's 'display-pane'
Vim Script
562
star
3

vim-quickhl

quickly highlight <cword> or visually selected word
Vim Script
229
star
4

vim-textmanip

easy text manupilation for vim
Vim Script
150
star
5

vagrant-snap

snapshoft management plugin for vagrant
Ruby
119
star
6

vim-ruby-xmpfilter

helper for ruby's xmpfilter or seeing_is_believing
Vim Script
115
star
7

vim-chef

jump to related file in chef's cookbook
Vim Script
70
star
8

vim-smalls

spot your cursor with simple search
Vim Script
64
star
9

vim-transform

Transform syntax!!
Vim Script
59
star
10

atom-cursor-history

Cursor position history manager
JavaScript
59
star
11

dotfiles

dotfiles
JavaScript
44
star
12

awesome-tadoku

Tadoku(倚θͺ­)+Ξ± γƒͺγ‚½γƒΌγ‚Ήγƒͺγƒ³γ‚―ι›†γ¨δΈ€ε£γ‚³γƒ‘γƒ³γƒˆ
Ruby
33
star
13

atom-quick-highlight

Highlight text quickly
JavaScript
33
star
14

atom-vim-mode-plus-ex-mode

Experiment to implement ex-mode for vim-mode-plus
JavaScript
30
star
15

atom-project-folder

Quickly add/remove project folder
JavaScript
26
star
16

vim-ezbar

&statusline configuration helper for minimalist.
Vim Script
25
star
17

atom-lazy-motion

Rapid cursor positioning with fuzzy search.
CoffeeScript
21
star
18

atom-vim-mode-plus-keymaps-for-surround

provides default keymap for surround
21
star
19

atom-open-this

Open file under cursor like `gf`(Vim), `C-x C-f`(Emacs)
CoffeeScript
19
star
20

atom-keystroke

define multi keystroke commands easily
JavaScript
17
star
21

atom-mprettier

Minimalistic prettier runner for more performant Atom startup
JavaScript
16
star
22

atom-vim-mode-visual-block

Add visual-blockwise operation to vim-mode.
CoffeeScript
15
star
23

atom-smalls

Rapid cursor positioning across any visible chars with search and jump.
CoffeeScript
15
star
24

atom-choose-pane

focus pane by label
JavaScript
15
star
25

atom-inline-git-diff

Inline git diffs in editor
JavaScript
14
star
26

vim-surround_custom_mapping

helper utility for tpope's surround.vim , which enables you setup filetype based custom mapping.
Vim Script
13
star
27

vim-unite-ack

narrow the Ack result with unite.vim
Vim Script
12
star
28

atom-markdown-toc-auto

auto insert and update table of contents on save
JavaScript
12
star
29

pxelerator

make PXE installation setup easy
Ruby
10
star
30

cmdline-fu

simple CLI front-end for http://www.commandlinefu.com/
10
star
31

atom-theme-switch

Switch theme quickly
JavaScript
9
star
32

tmux_config

my tmux configration
Ruby
9
star
33

vim-nerdtree_plugin_collections

my personal nerdtree plugin collections
Vim Script
9
star
34

atom-vim-mode-plus-move-selected-text

Move selected text like object
CoffeeScript
8
star
35

cram-vocabulary

JavaScript
7
star
36

js-study

JavaScript self study notes
7
star
37

my-vim-config

my vimrc
Vim Script
7
star
38

build-kikutan

Build kikutan(キクタン) like sound album from text using GoogleTTS
Ruby
6
star
39

atom-paner

Pane manipulation helper
JavaScript
6
star
40

atom-toggle

Toggle keyword
JavaScript
6
star
41

vim-macvim-transparency

change MacVim's window transparency with shortcut
Vim Script
6
star
42

anki-accelerate-image-drag-and-drop

Accelerate workflow when you drag&drop image to a cards repetitively
Python
5
star
43

go-study

Golang self study notes β€” Edit
Go
5
star
44

vim-fthook

provide very simple filetype hook facility.
Vim Script
5
star
45

vim-phrase

gather userful phrase for reference
Vim Script
5
star
46

atom-isearch

Incremental search for Atom
CoffeeScript
5
star
47

atom-project-find-navigation

Improve project-find-result navigation by dirty hack.
CoffeeScript
5
star
48

atom-clip-history

Paste from clipboard history like emacs' kill-ring
JavaScript
5
star
49

phrase-t9md

phrase of t9md
Ruby
4
star
50

vim-textobj-function-ruby

textobj for ruby's method depending on vim-ruby's ]M and [m
Vim Script
4
star
51

atom-demo-mode

Show command dispatch at hover indicator / also provide service for special integration
JavaScript
4
star
52

vim-learn

CSS
4
star
53

atom-transformer

Transform something
JavaScript
3
star
54

chef-solo-quickstart

Quick start to learn chef's DSL with chef-solo
Ruby
3
star
55

vim-underlinetag

underline Tag to know which word I could jump with C-]
Vim Script
3
star
56

atom-narrow-git-ls

narrow-git-ls
JavaScript
3
star
57

vim-unite-experiment

my local experiment for unite.vim
Vim Script
3
star
58

atom-vim-mode-plus-project-find-from-search

Seamless flow from vmp's search to find-and-replace's project-find
CoffeeScript
3
star
59

iTerminitor

iTerm setup easily
Ruby
2
star
60

atom-vim-mode-plus-replace-with-execution

TransformString with result of execution
JavaScript
2
star
61

vagrant_example

several example of vagrant and chef or puppet
Ruby
2
star
62

aptsync

apt-mirror like utility. diff: KISS, short code, use rsync.
Ruby
2
star
63

vim-resizewin

toggle winsize horizontally vertically or both maximized.
Vim Script
2
star
64

vim-snipplr

vim frontend for http://snipplr.com/
2
star
65

vim-unite-lines

nallowing lines from current buffer
Vim Script
2
star
66

bulk-screen-capture

bulk screen capture script intended to use for Anki
Python
2
star
67

puppet-pi-mode.el

Puppet pi mode for emacs enable you to use pi (puppet type reference cmd-line-tool) from Emacs.
Emacs Lisp
2
star
68

vim-quicktag

automatically generate tags
Vim Script
2
star
69

atom-phrase

Collect phrase, and refer quickly.
CoffeeScript
2
star
70

fu

search www.commandlinefu.com from CLI
Go
2
star
71

t9md

test
2
star
72

vim-tryit

try code in sandbox file.
Vim Script
2
star
73

bdd-infra-train

misc files for bdd-infra
Ruby
2
star
74

ruby_kata

practice for ruby over and over again.
Ruby
1
star
75

atom-mgit

minimum git wrapper just for me
JavaScript
1
star
76

atom-vocabuilder

Let me vocabuild!
JavaScript
1
star
77

atom-hydrogen-helpers

misc helpers for hydrogen
JavaScript
1
star
78

snippy

snippet sharing board based on Flask, teach me python and flask
Python
1
star
79

vim-jslike-oop

VimScript JavaScript Like OOP experiment
Vim Script
1
star
80

puppet-tags.rb

generate tags for puppet's external DSL
1
star
81

atom-focus-pane-or-panel

change focus or pane or panel seamlessly
CoffeeScript
1
star
82

vim-ruby_eval

evaluate text fragment as ruby then insert or print
Ruby
1
star
83

atom-vim-mode-plus-plugin-sample

Sample project for package as vim-mode-plus's plugin
JavaScript
1
star
84

atom-vim-mode-plus-auto-ime

automatically change ime when vim mode changes
JavaScript
1
star
85

ruby-network-programming-learning

teach ruby network programming to myself
Ruby
1
star
86

vim2tmux.vim

send line from buffer to tmux's pane!!
Vim Script
1
star
87

vim-misc-experiment

several experimental before becoming plugin.
Vim Script
1
star
88

atom-try

Paste fragment of code into try buffer then try it!
CoffeeScript
1
star
89

vim-paste-marker

vim plugin , this enables you to first put mark as target then yank to distined target.
Vim Script
1
star
90

vim-mapswap

swap keymap temporarily
Vim Script
1
star
91

atom-google-translate

translate and write to editor in dock or split-pane
JavaScript
1
star