Nvim Swift Fuzzy Search

nvim fuzzy file + symbol search for Swift (fzf.vim + universal-ctags)

Replicates Xcode's Cmd+Shift+O ("Open Quickly") in nvim: Ctrl-P fuzzy-finds files, ,O/,t fuzzy-find symbols (classes, structs, enums, protocols, extensions, funcs, vars, enum cases, typealiases) project-wide / in the current buffer.

Config lives in two global, machine-level locations, so once set up they apply to every Swift project on the machine:

• ~/.config/nvim/init.vim
• ~/.ctags.d/swift.ctags

Only the tags file itself (tags, generated inside each project root) is per-project.

Why this needs custom setup (root causes)

1. macOS ships a BSD ctags stub at /usr/bin/ctags (forwards to Xcode's ancient ctags via xcrun) that shadows Homebrew's modern ctags in most shell PATHs, and it lacks -R (recursive) support entirely.
2. Even Homebrew's universal-ctags bottle has no Swift language parser compiled in — ctags --list-languages will not list Swift. It silently tags zero symbols from .swift files with no error.
3. Because of #1, fzf.vim's :Tags/:BTags may pick up the broken ctags, or (because of #2) generate an empty/useless tags file. If a stale tags file already exists in the project root, fzf.vim won't re-prompt to regenerate it — it just keeps using the bad file.

Setup steps (run once per machine)

1. Install fzf and universal-ctags:

   brew install fzf universal-ctags
   

2. Confirm Homebrew's ctags actually has Swift support — it won't, by default:

   /opt/homebrew/bin/ctags --list-languages | grep -i swift
   

   If empty (expected), continue to step 3.

3. Create ~/.ctags.d/swift.ctags (ctags reads every .ctags file in this dir automatically, for every project). Use PCRE2 ({pcre2} suffix on each rule) since the default POSIX regex engine doesn't support non-capturing groups (?:...):

   --langdef=Swift
   --langmap=Swift:.swift
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open)[ \t]+)?(?:final[ \t]+)?class[ \t]+([a-zA-Z0-9_]+)/\1/c,classes/{pcre2}
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open)[ \t]+)?struct[ \t]+([a-zA-Z0-9_]+)/\1/s,structs/{pcre2}
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open)[ \t]+)?enum[ \t]+([a-zA-Z0-9_]+)/\1/e,enums/{pcre2}
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open)[ \t]+)?protocol[ \t]+([a-zA-Z0-9_]+)/\1/p,protocols/{pcre2}
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open)[ \t]+)?extension[ \t]+([a-zA-Z0-9_.]+)/\1/x,extensions/{pcre2}
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open|static|final|override|mutating|convenience|required|class)[ \t]+)*func[ \t]+([a-zA-Z0-9_]+)/\1/f,functions/{pcre2}
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open|static|final|override|lazy|weak)[ \t]+)*(?:let|var)[ \t]+([a-zA-Z0-9_]+)/\1/v,variables/{pcre2}
   --regex-Swift=/^[ \t]*case[ \t]+([a-zA-Z0-9_]+)/\1/m,enumcase/{pcre2}
   --regex-Swift=/^[ \t]*(?:(?:public|private|internal|fileprivate|open)[ \t]+)?typealias[ \t]+([a-zA-Z0-9_]+)/\1/t,typealiases/{pcre2}
   

   Verify: /opt/homebrew/bin/ctags --list-languages | grep -i swift should now print Swift.

4. Edit ~/.config/nvim/init.vim:

   • Add fzf plugins to the vim-plug block:

     Plug '/opt/homebrew/opt/fzf'
     Plug 'junegunn/fzf.vim'
     

   • Near the top of the file (before anything else runs), prepend Homebrew's bin dir to nvim's own $PATH so nvim never resolves to the broken system ctags, regardless of the user's shell PATH order:

     if isdirectory('/opt/homebrew/bin')
         let $PATH = '/opt/homebrew/bin:' . $PATH
     endif
     

   • Add keybindings + restrict tag generation to actual code languages (keeps markdown/svg/yaml/json prose and data out of symbol search results):

     nnoremap <C-p> :Files<CR>
     nnoremap <leader>O :Tags<CR>
     nnoremap <leader>t :BTags<CR>
     let g:fzf_layout = { 'window': { 'width': 0.9, 'height': 0.6 } }
     let g:fzf_tags_command = 'ctags -R --languages=Swift,C,C++'
     

     (Check for an existing <leader>o/<leader>t mapping conflict first — e.g. this user already had <leader>o bound to spell-check toggle, so ,t/,O were chosen instead of reusing o.)
   • Run nvim --headless "+PlugInstall --sync" +qa to install the new plugins.

Setup steps (run once per new Swift project)

1. cd into the project and open nvim.
2. Run ,O (or :Tags). Since no tags file exists yet, fzf.vim prompts tags not found. Generate? (y/N) — answer y. This runs the g:fzf_tags_command above and writes tags to the project root.
3. Add tags to that project's .gitignore — it's a generated file and should never be committed.

Troubleshooting

• "Failed to create tags" / no results despite symbol existing: run /opt/homebrew/bin/ctags --list-languages | grep -i swift — if empty, step 3 (the custom swift.ctags langdef) is missing or has a syntax error. Check for ctags: Warning: ... Failed in compiling the regex pattern on stderr, which means a rule is missing its {pcre2} flag.
• Still no results after fixing the parser: check for a stale tags file already sitting in the project root (ls tags) generated before the fix — delete it and regenerate manually:

  rm -f tags && /opt/homebrew/bin/ctags -R --languages=Swift,C,C++ .
  

• Verify which ctags a plain shell resolves to (may differ from what nvim uses, since nvim's $PATH is patched in init.vim):

  which -a ctags
  

• Sanity-check a single file directly:

  /opt/homebrew/bin/ctags -f - path/to/File.swift