{"id":17982849,"url":"https://github.com/t9md/atom-narrow","last_synced_at":"2025-03-25T19:31:43.341Z","repository":{"id":55456503,"uuid":"58503640","full_name":"t9md/atom-narrow","owner":"t9md","description":"narrow something","archived":false,"fork":false,"pushed_at":"2020-12-29T18:13:19.000Z","size":1437,"stargazers_count":109,"open_issues_count":21,"forks_count":12,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-20T17:38:35.604Z","etag":null,"topics":["atom","editor","vim-mode","vim-mode-plus"],"latest_commit_sha":null,"homepage":"https://atom.io/packages/narrow","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t9md.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-11T01:06:35.000Z","updated_at":"2024-06-20T01:54:26.000Z","dependencies_parsed_at":"2022-08-15T00:40:34.329Z","dependency_job_id":null,"html_url":"https://github.com/t9md/atom-narrow","commit_stats":null,"previous_names":[],"tags_count":110,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t9md%2Fatom-narrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t9md%2Fatom-narrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t9md%2Fatom-narrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t9md%2Fatom-narrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t9md","download_url":"https://codeload.github.com/t9md/atom-narrow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245530297,"owners_count":20630522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atom","editor","vim-mode","vim-mode-plus"],"created_at":"2024-10-29T18:15:23.300Z","updated_at":"2025-03-25T19:31:42.959Z","avatar_url":"https://github.com/t9md.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# narrow\n\n[![Build Status](https://travis-ci.org/t9md/atom-narrow.svg?branch=master)](https://travis-ci.org/t9md/atom-narrow)\n\nnarrow something.  \nCode navigation tool inspired by unite.vim, emacs-helm.  \nMore information on [wiki](https://github.com/t9md/atom-narrow/wiki)\n\n![narrow](https://raw.githubusercontent.com/t9md/t9md/4df5df86884a25bf8b62dc3b605df050a06c8232/img/atom-narrow/narrow.gif)\n\n# What's this?\n\n- Provide narrowing UI like emacs-helm and unite/denite.vim.\n- **Not** aiming to become \"can open anything from narrow-able UI\" package.\n- Primal focus is on **code-navigation**.\n- Provider provide items( e.g. by `search` files in project ), you can filter items by query to narrow down further.\n- As you move cursor on active-editor, **current** item on narrow-ui is automatically synced.\n- You no longer lost like \"Where am I?\" when you are working on multiple files.\n- Let narrow navigate to next/previous item to aid your concentration.\n- Edit with confidence for no-overlook by direct-edit( edit on `ag search result` on narrow-editor then apply changes to real-file ).\n- In mind\n  - keyboard navigation.\n  - [vim-mode-plus](https://atom.io/packages/vim-mode-plus) integration( I'm also maintainer of vim-mode-plus ).\n- Also see [UseCase on wiki](https://github.com/t9md/atom-narrow/wiki/UseCase) and [Q\u0026A on this doc](#qa)\n\n# Roles in play.\n\n- `narrow-editor` or `narrow-ui`: filter items by query and render items.\n- `narrow-provider`: Provide items to narrow.\n\n### overview\n\n![overview](https://raw.githubusercontent.com/t9md/t9md/1654820b1f064aa11e087c7b3c1d6ce14ab03449/img/atom-narrow/overview.png)\n\n### control bar\n\n![control-bar](https://raw.githubusercontent.com/t9md/t9md/37f70896cb383f455f7a18a04d559e8adb05502c/img/atom-narrow/control-bar.png)\n\n# Bundled providers\n\nYou can check GIFs for all bundled provider [here](https://github.com/t9md/atom-narrow/wiki/Provider).  \nI use `scan`, `search`, `git-diff-all`, `symbols` in daily-basis, for other providers I don't use much.  \n\n- `scan`: Scan current editor.\n- `search`: Search by `ag`( you need to install `ag` by yourself).\n- `atom-scan`: Similar to `search` but use Atom's `atom.workspace.scan`.\n- `fold`: Provide fold-starting rows as item.\n- `git-diff-all`: Show all modified state file across project.\n- `symbols`: Provide symbols for current file.\n- `project-symbols`: Provide project-wide symbols information by reading `tags` file.\n\n# Quick tour\n\nTo follow this quick-tour, you don't need custom keymap.\n\n### Step1. basic by using `narrow:scan`\n\n1. Open some text-editor, then via command-palette, invoke `Narrow Scan`.\n2. `narrow-editor` opened, Initial items are each lines on editor. As you type, you can narrow items.\n3. When you type `apple` as query. all `apple` matching items are listed.\n4. You can move normal `up`, `down`(or `j`, `k` in read-only mode) key to quick-preview items.\n5. `enter` to confirm. When confirmed, `narrow-editor` closed.\n\nThe read-only mode is enabled by default.\n\n### Step2. navigate from outside of `narrow-editor`.\n\n1. Open some text-editor, then via command-palette, invoke `Narrow Scan`.\n2. `narrow-editor` opened. As you type, you can narrow items.\n3. Click invoking editor. And see your clicked position is automatically reflected `narrow-editor`.\n4. `ctrl-cmd-n` to move to `next-item`, `ctrl-cmd-p` to move to `previous-item`.\n  - If you are vim-mode-plus user, You can use `tab` and `shift-tab`.\n5. You can close `narrow-editor` by `ctrl-g`( no need to focus `narrow-editor` ).\n6. If you want to change narrow-query, you have to focus to `narrow-editor`\n  - Use `ctrl-cmd-f`( `narrow:focus` ) to focus `narrow-editor`.\n  - Use `ctrl-cmd-i`( `narrow:focus-prompt` ) to directly focus narrow-editor's query prompt row.\n  - Both commands are available from outside/inside of narrow-editor.\n7. These navigation keymaps are available for all provider(e.g. `search`, `fold` etc).\n\n### Step3. direct-edit\n\nDirect-edit is \"edit on `narrow-editor` then save to real-file\" feature.  \nAvailable for following providers.\n\n- `scan`\n- `search`\n- `atom-scan`\n\n⚠️ This operation is dangerous, since you can update multiple files at once.\n⚠️ You have to be careful enough to use this feature, don't use this without understanding what you are doing.\n⚠️ I can say sorry, but I can not recover file for you.  \n\n1. Open file from project, place cursor for variable name `hello`\n2. Then invoke `Narrow Search By Current Word`.\n3. All `hello` matching items are shows up on narrow-editor.\n4. If you want, you can further narrow by query.\n5. Then edit narrow-editor's text **directly**.\n  - Place cursor on `hello`. Then `ctrl-cmd-g`(`find-and-replace:select-all`), then type `world`.\n6. Invoke `Narrow Ui: Update Real File` from command-palette.\n7. DONE, changes you made on narrow-editor items are applied to real-file(and saved).\n8. You can undo changes by re-edit items on narrow-editor and reapply changes by `Narrow Ui: Update Real File`.\n\n### Step4. [Experimental] search keyword by mouse\n\n1. Set `Search.startByDoubleClick` to `true` from settings-view.\n2. Double click keyword in editor.\n3. Each time you double click keyword, new narrow-editor open and old one is replaced.\n4. You can continue double click which ever narrow-editor or normal-editor.\n\n# Commands\n\n### Available in all text-editor\n\n##### Other\n\n- `narrow:focus`: ( `ctrl-cmd-f` ) Focus to `narrow-editor`, if executed in `narrow-editor`, it re-focus to original editor.\n- `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.\n- `narrow:refresh`: Manually refresh items in `narrow-editor`.\n- `narrow:close`: ( `ctrl-g` ) Close currently opened `narrow-editor` one at a time.\n- `narrow:next-item`: ( `ctrl-cmd-n` ) Move cursor to position of next-item.\n- `narrow:previous-item`: ( `ctrl-cmd-p` ) Move cursor to position of previous-item.\n- `narrow:reopen`: ( no default keymap ) Reopen closed narrow editor up to 10 recent closed.\n- `narrow:query-current-word`: ( `ctrl-cmd-e` ) Replace active `narrow-editor`'s query with cursor word.\n- `narrow:previous-query-history`: ( `ctrl-cmd-[` ) Replace active `narrow-editor`'s query with previous history entry.\n- `narrow:next-query-history`: ( `ctrl-cmd-]` ) Replace active `narrow-editor`'s query with next history entry.\n\n##### Invoke narrow provide\n\nNo keymaps are provided\n\n- `narrow:scan`\n- `narrow:scan-by-current-word`\n- `narrow:fold`\n- `narrow:fold-by-current-word`\n- `narrow:search`: [ag](https://github.com/ggreer/the_silver_searcher) search. need install by your self.\n- `narrow:search-by-current-word`\n- `narrow:search-current-project`\n- `narrow:search-current-project-by-current-word`\n- `narrow:atom-scan`\n- `narrow:atom-scan-by-current-word`\n- `narrow:symbols`\n- `narrow:symbols-by-current-word`\n- `narrow:project-symbols`:\n- `narrow:project-symbols-by-current-word`:\n- `narrow:git-diff-all`\n\n### Available in narrow-editor(narrow-ui)\n\nThe `!vmp` followed by keymap means \"which keymap is not available for vim-mode-plus user\".  \nIf you want use these keymap with `vim-mode-plus`, set it by yourself.  \nSee [Wiki](https://github.com/t9md/atom-narrow/wiki/ExampleKeymap#restore-vim-mode-plus-specific-default-keymap-defined-old-version)  \n\n- `core:confirm`: ( `enter` ) Close `narrow-editor`\n- `narrow-ui:confirm-keep-open`: keep open `narrow-editor`\n- `narrow-ui:open-here`: Open item at same pane of UI's pane.\n- `narrow-ui:preview-item`: Preview currently selected item manually( you don't need in most case ).\n- `narrow-ui:preview-next-item`: ( `tab` ) Preview next-item without moving cursor from `narrow-editor`'s query prompt.\n- `narrow-ui:preview-previous-item`: ( `shift-tab` ) Preview next-item without moving cursor from `narrow-editor`'s query prompt.\n- `narrow-ui:toggle-auto-preview`: ( `ctrl-r` for non-vim-mode-plus user) Disable/enable auto-preview for this `narrow-editor`.\n- `narrow-ui:move-to-prompt`: `ctrl-cmd-i`\n- `narrow-ui:stop-insert`: `escape`\n- `narrow-ui:update-real-file`: Apply changes made in `narrow-editor` to real-file.( edit in `narrow-editor` then save it to real file. )\n- `narrow-ui:protect`: No keymap by default, Protect narrow-editor from being destroyed by `narrow:close`( `ctrl-g` ).\n- `narrow-ui:exclude-file`: `backspace`, Exclude items which matches filePath of currently selected item's.\n- `narrow-ui:clear-excluded-files`: `ctrl-backspace`, Clear excluded files list.\n- `narrow-ui:select-files`: `cmd-backspace`, interactively select which filePath's items to appear on `narrow-editor`.\n- `narrow-ui:toggle-search-whole-word`: `alt-cmd-w`\n- `narrow-ui:toggle-search-ignore-case`: `alt-cmd-c`\n- `narrow-ui:toggle-search-use-regex`: `alt-cmd-/`\n- `narrow-ui:start-insert`: `I`(`!vmp`), `a`(`!vmp`)\n- `narrow-ui:move-to-next-file-item`: `n`(`!vmp`)\n- `narrow-ui:move-to-previous-file-item`: `p`(`!vmp`)\n- `narrow-ui:relocate`: No keymap by default, Switch location where ui opened between `center` workspace and `bottom` dock.\n\n# Keymaps\n\nNo keymap to invoke narrow provider(e.g `narrow:scan`).  \nStart it from command-palette or set keymap in `keymap.cson`.\n\n⚠️ [default keymap](https://github.com/t9md/atom-narrow/blob/master/keymaps/narrow.cson) is not yet settled, this will likely to change in future version.   \n\n### My keymap(vim-mode-plus user) and config\n\n\n###### `config.cson`\n\n```coffeescript\n  narrow:\n    SelectFiles:\n      rememberQuery: true\n    confirmOnUpdateRealFile: false\n```\n\n###### `keymap.cson`\n\nExplanation of my keymap.\n\n- `cmd-f`: To focus to narrow-editor AND focus-back to original-editor\n- `cmd-i`: To focus to narrow-editor's prompt AND focus-back to original-editor\n- `cmd-e`:\n  - When workspace has no `narrow-edior` on workspace: start `narrow:search-by-current-word`.\n  - When workspace has at least one `narrow-edior`: `query-current-word`( by default keymap).\n    - Replace active `narrow-edior`'s query with cursor-word.\n- `cmd-[`: `narrow:previous-query-history` Recall previous history\n- `cmd-]`: `narrow:next-query-history`, Recall next history\n- `ctrl-g`: Close `narrow-editor` from wherever.\n- `tab`, `shift-tab`: to move to next/previous item.\n- `;`: confirm current-item without closing `narrow-editor`, I can close `narrow-editor` by `ctrl-g`.\n\n```coffeescript\n# From outside of narrow-editor\n# -------------------------\n\n# `cmd-e` start `search-by-current-word` only when workspace does NOT have `narrow-editor`.\n# NOTE: When workspace.has-narrow, `cmd-e` is mapped to `query-current-word` by default.\n'atom-workspace:not(.has-narrow) atom-text-editor.vim-mode-plus:not(.insert-mode)':\n  'cmd-e': 'narrow:search-by-current-word'\n\n'atom-text-editor.vim-mode-plus:not(.insert-mode)':\n  'ctrl-z':      'narrow:reopen'\n  'space f':     'narrow:fold'\n  'cmd-o':       'narrow:symbols-by-current-word'\n  'cmd-shift-o': 'narrow:project-symbols-by-current-word'\n  'cmd-r':       'narrow:symbols' # Override default cmd-r\n  'cmd-shift-r': 'narrow:project-symbols' # Override default cmd-shift-r\n  'space l':     'narrow:scan'\n  'cmd-l':       'narrow:scan-by-current-word'\n  'space s':     'narrow:search'\n  'space G':     'narrow:git-diff-all'\n\n# When workspace has narrow-editor\n'atom-workspace.has-narrow atom-text-editor.vim-mode-plus.normal-mode':\n  'cmd-f': 'narrow:focus' # focus to narrow-editor\n  'cmd-i': 'narrow:focus-prompt' # focus to prompt of narrow-editor\n\n  # Following three command have ctrl- prefixed by default to avoid conflicts.\n  # But I don' care conflict, prefer more accessible keymap.\n  'cmd-[': 'narrow:previous-query-history'\n  'cmd-]': 'narrow:next-query-history'\n  'cmd-e': 'narrow:query-current-word'\n\n# narrow-editor regardless of mode of vim\n'atom-text-editor.narrow.narrow-editor[data-grammar=\"source narrow\"]':\n  'cmd-f': 'narrow:focus'\n  'cmd-i': 'narrow:focus-prompt' # cmd-i to return to calling editor.\n\n  # Danger: apply change on narrow-editor to real file by `cmd-s`.\n  'cmd-s': 'narrow-ui:update-real-file'\n\n  # Move ui in between bottom dock and center workspace.\n  'cmd-t': 'narrow-ui:relocate'\n\n'atom-workspace.has-narrow atom-text-editor.vim-mode-plus.normal-mode,\n  atom-workspace.has-narrow atom-text-editor.vim-mode-plus.visual-mode':\n    'cmd-e': 'narrow:query-current-word' # set current word as query of active ui.\n\n'atom-text-editor.narrow.narrow-editor.vim-mode-plus.normal-mode':\n  'g g': 'narrow-ui:move-to-prompt'\n  's': 'narrow-ui:select-files'\n  ';': 'narrow-ui:confirm-keep-open'\n  'n': 'narrow-ui:move-to-next-file-item'\n  'p': 'narrow-ui:move-to-previous-file-item'\n```\n\n# Recommended configuration for other packages.\n\n- Suppress autocomplete-plus's popup on narrow-editor\n- Disable vim-mode-plus's highlight-search on narrow-editor\n\n```coffeescript\n\"*\":\n  \"autocomplete-plus\":\n    suppressActivationForEditorClasses: [\n      # snip\n      \"narrow\"\n    ]\n  # snip\n  \"vim-mode-plus\":\n    highlightSearchExcludeScopes: [\n      \"narrow\"\n    ]\n```\n\n# Notes for vim-mode-plus user\n\n## ⚠️ Limitation: for compatibility with vim-mode-plus.\n\n- If you use atom v1.16.0 or older,\n  - Don't enable `vim-mode-plus.automaticallyEscapeInsertModeOnActivePaneItemChange`\n  - If you enabled, each query input on narrow-editor of `search` provider cause mode-change from `insert-mode` to `normal-mode`.\n- If you use atom v1.17.0 or older( currently in beta ).\n  - This limitation is no longer exists.\n\n## Keymap\n\nLearn [keymap](https://github.com/t9md/atom-narrow/blob/master/keymaps/narrow.cson) available as default.  \ne.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).  \n\n## Start narrow from vim-mode-plus's search-input-form\n\nIf you are [vim-mode-plus](https://atom.io/packages/vim-mode-plus) user.\nFollowing command are available from vim-mode-plus's search(`/` or `?`) mini-editor.\n\n- `vim-mode-plus-user:narrow:scan`\n- `vim-mode-plus-user:narrow:search`\n- `vim-mode-plus-user:narrow:search-current-project`\n- `vim-mode-plus-user:narrow:atom-scan`\n\n## How to edit item-area for direct-edit.\n\n- In narrow-editor, `i`, `a` in `normal-mode` move cursor to prompt line.\n- So when you want to edit items itself for `direct-edit` and `update-real-file` use other key to enter `insert-mode`.\n- `I` is intentionally mapped to `vim-mode-plus:activate-insert-mode` which is normally mapped to `i`.\n  - Which might not be intuitive, but I want make item mutatation bit difficult. So user have to type `I`.\n- Other than `I`, you can start `insert-mode` by `A`, `c` etc..\n\n# Q\u0026A\n\n### What providers are you seriously using?\n\nIn daily editing, I use.\n\n`scan`, `search`, `git-diff-all`, `symbols`.\n\nWhy I'm not using others? reason is here.\n\n- `fold`: Since it similar to `symbols`.\n- `atom-scan`: it is provided for windows user who can't use `search`(need `ag` or `rg`).\n\n### Noticed I can close `narrow-editor` by normal `cmd-w`(`core:close`). Why I need `narrow:close`? What's the difference?\n\nThe biggest difference is `narrow:close` restore editor state(scrollTop, fold, active pane item) if user did only `preview` from startup.\n\n- `narrow:close`: Close `narrow-editor` and **restore editor state** when it appropriate. Also can close `narrow-editor` regardless of current active-editor.\n- `core:close`: Just destroy `narrow-editor`.\n\nUse whichever you want accordingly.\nI 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).\n\n### How can I exclude particular file from `narrow:search`\n\n##### Use `backspace` on item\n\n- Use `backspace` to exclude particular file from result.\n- `ctrl-backspace` clear excluded file list and refresh\n- These keymaps are available in `narrow-editor` and you are in `read-only-mode`\n\n##### Use `select-files` provider\n\n- You can launch `select-files` by `cmd-backspace` or clicking `folder-icon` on **control-bar**.\n\n1. search `editor` by `narrow:search`, you see lots of `editor` mached items\n2. But you want exclude items in markdown file?\n  - launch `select-files`, all file paths are listed as item.\n  - Then type `md` on query, you see markdown filepath that macheed `md`.\n  - Then add `!`, now your query is `md!`, this is treated as all files **not** matching `md`.\n  - `enter` to confirm.\n3. You see items with items in markdown files are excluded.\n4. You can re-fine files to exclude by re-launching `select-files`.\n  - e.g. To exclude `spec` folder, you can add `spec/!` as query.\n  - e.g. To include `.js` file only, you can set query to `.js`.\n\n### Want to skip to `next-file`, `previous-file`\n\n- Use `n`, `p` in `read-only` mode.\n\n### I want `narrow:symbols` always shows up at right-most pane and don't want to close.\n\n1. Open `narrow:symbols`( or maybe you want to use `narrow:fold` )\n2. Move this `narrow-editor` by drag and drop to the place where you want.\n3. From command-palette, execute `Narrow Ui: Protect`. Now `narrow-editor` protected.\n4. Protected `narrow-editor` is not closed by `ctrl-g`( `narrow:close` ), and not closed by confirm by `enter`.\n5. To close, use normal `cmd-w` or close button on tab.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft9md%2Fatom-narrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft9md%2Fatom-narrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft9md%2Fatom-narrow/lists"}