bashly-framework · DannyBen · Feb 20, 2026 · Feb 19, 2026 · Feb 20, 2026 · Feb 20, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,5 @@
+# AGENTS.md
+
+## Notes
+
+- `CHANGELOG.md` is generated using `git changelog`; do not edit it manually.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,203 +1,161 @@
 Changelog
 ========================================
 
-v0.7.4 - 2026-02-19
-----------------------------------------
-
-- Fix completion escaping [`dce16c3`](https://github.com/bashly-framework/completely/commit/dce16c3)
-- Refactor template filter function [`834ed78`](https://github.com/bashly-framework/completely/commit/834ed78)
-- Update completions installer paths [`338d567`](https://github.com/bashly-framework/completely/commit/338d567)
-- Compare [`v0.7.3..v0.7.4`](https://github.com/bashly-framework/completely/compare/v0.7.3..v0.7.4)
-
-
-v0.7.3 - 2025-09-24
-----------------------------------------
-
-- Add support for reading config from stdin and writing to stdout [`764fb36`](https://github.com/bashly-framework/completely/commit/764fb36)
-- Fix repeating final completion [`0029c4e`](https://github.com/bashly-framework/completely/commit/0029c4e)
-- Refactor installer with new io / string builders [`cb91679`](https://github.com/bashly-framework/completely/commit/cb91679)
-- Add support for `generate --install` [`c5a877e`](https://github.com/bashly-framework/completely/commit/c5a877e)
-- Compare [`v0.7.2..v0.7.3`](https://github.com/bashly-framework/completely/compare/v0.7.2..v0.7.3)
-
-
 v0.7.2 - 2025-08-04
 ----------------------------------------
 
-- Fix JSON schema [`3cc3ef6`](https://github.com/bashly-framework/completely/commit/3cc3ef6)
-- Drop support for Ruby 3.0 and 3.1 [`7ff8bd8`](https://github.com/bashly-framework/completely/commit/7ff8bd8)
-- Compare [`v0.7.1..v0.7.2`](https://github.com/bashly-framework/completely/compare/v0.7.1..v0.7.2)
+- Fix JSON schema
+- Drop support for Ruby 3.0 and 3.1
 
 
 v0.7.1 - 2025-04-04
 ----------------------------------------
 
-- Add support for modifying the `complete` command options [`690c264`](https://github.com/bashly-framework/completely/commit/690c264)
-- Compare [`v0.7.0..v0.7.1`](https://github.com/bashly-framework/completely/compare/v0.7.0..v0.7.1)
+- Add support for modifying the `complete` command options
 
 
 v0.7.0 - 2024-11-29
 ----------------------------------------
 
-- Update instructions and template for obtaining list of git branches [`8cdfabd`](https://github.com/bashly-framework/completely/commit/8cdfabd)
-- Add support for nested configuration [`742e3cd`](https://github.com/bashly-framework/completely/commit/742e3cd)
-- Add `completely init --nested` and explain nested syntax in the README [`f1e17ed`](https://github.com/bashly-framework/completely/commit/f1e17ed)
-- Compare [`v0.6.3..v0.7.0`](https://github.com/bashly-framework/completely/compare/v0.6.3..v0.7.0)
+- Update instructions and template for obtaining list of git branches
+- Add support for nested configuration
+- Add `completely init --nested` and explain nested syntax in the README
 
 
 v0.6.3 - 2024-07-05
 ----------------------------------------
 
-- Allow using colon, semicolon and equal sign in completions [`a9e6a6e`](https://github.com/bashly-framework/completely/commit/a9e6a6e)
-- Check output with shfmt [`3f7ae7e`](https://github.com/bashly-framework/completely/commit/3f7ae7e)
-- Revert wordbreak (colon) patch [`24f9d3d`](https://github.com/bashly-framework/completely/commit/24f9d3d)
-- Compare [`v0.6.2..v0.6.3`](https://github.com/bashly-framework/completely/compare/v0.6.2..v0.6.3)
+- Allow using colon, semicolon and equal sign in completions
+- Check output with shfmt
+- Revert wordbreak (colon) patch
 
 
 v0.6.2 - 2024-02-08
 ----------------------------------------
 
-- Update possible completions installation directories [`2bc93a7`](https://github.com/bashly-framework/completely/commit/2bc93a7)
-- Build docker images automatically [`4d20dfd`](https://github.com/bashly-framework/completely/commit/4d20dfd)
-- Compare [`v0.6.1..v0.6.2`](https://github.com/bashly-framework/completely/compare/v0.6.1..v0.6.2)
+- Update possible completions installation directories
+- Build docker images automatically
 
 
 v0.6.1 - 2023-06-23
 ----------------------------------------
 
-- Add ability to uninstall a completion script [`67b6715`](https://github.com/bashly-framework/completely/commit/67b6715)
-- Compare [`v0.6.0..v0.6.1`](https://github.com/bashly-framework/completely/compare/v0.6.0..v0.6.1)
+- Add ability to uninstall a completion script
 
 
 v0.6.0 - 2023-06-23
 ----------------------------------------
 
-- Refactor install command and add an Installer model [`b1341fa`](https://github.com/bashly-framework/completely/commit/b1341fa)
-- Drop support for Ruby 2.7 [`151eff1`](https://github.com/bashly-framework/completely/commit/151eff1)
-- Change exception classes [`3ce16ac`](https://github.com/bashly-framework/completely/commit/3ce16ac)
-- Compare [`v0.5.4..v0.6.0`](https://github.com/bashly-framework/completely/compare/v0.5.4..v0.6.0)
+- Refactor install command and add an Installer model
+- Drop support for Ruby 2.7
+- Change exception classes
 
 
 v0.5.4 - 2023-04-21
 ----------------------------------------
 
-- Add `completely install` command [`2fbd879`](https://github.com/bashly-framework/completely/commit/2fbd879)
-- Compare [`v0.5.3..v0.5.4`](https://github.com/bashly-framework/completely/compare/v0.5.3..v0.5.4)
+- Add `completely install` command
 
 
 v0.5.3 - 2023-01-31
 ----------------------------------------
 
-- Upgrade dependencies [`211166a`](https://github.com/bashly-framework/completely/commit/211166a)
-- Compare [`v0.5.2..v0.5.3`](https://github.com/bashly-framework/completely/compare/v0.5.2..v0.5.3)
+- Upgrade dependencies
 
 
 v0.5.2 - 2022-12-02
 ----------------------------------------
 
-- Improve test command output and allow multiple complines in one run [`e924571`](https://github.com/bashly-framework/completely/commit/e924571)
-- Compare [`v0.5.1..v0.5.2`](https://github.com/bashly-framework/completely/compare/v0.5.1..v0.5.2)
+- Improve test command output and allow multiple complines in one run
 
 
 v0.5.1 - 2022-11-28
 ----------------------------------------
 
-- Refactor with rubocop [`42b996d`](https://github.com/bashly-framework/completely/commit/42b996d)
-- Fix broken script when wildcards follow the first word [`63b77d1`](https://github.com/bashly-framework/completely/commit/63b77d1)
-- Show warning when running the test command on an invalid file [`de7ede0`](https://github.com/bashly-framework/completely/commit/de7ede0)
-- Compare [`v0.5.0..v0.5.1`](https://github.com/bashly-framework/completely/compare/v0.5.0..v0.5.1)
+- Refactor with rubocop
+- Fix broken script when wildcards follow the first word
+- Show warning when running the test command on an invalid file
 
 
 v0.5.0 - 2022-09-04
 ----------------------------------------
 
-- Add docker release [`39acd6e`](https://github.com/bashly-framework/completely/commit/39acd6e)
-- Fix shellcheck SC2162 in the generated script [`9e703ec`](https://github.com/bashly-framework/completely/commit/9e703ec)
-- Fix shellcheck SC2124 in the generated script [`2d23c51`](https://github.com/bashly-framework/completely/commit/2d23c51)
-- Hide flag completion unless input ends with a hyphen [`c15d705`](https://github.com/bashly-framework/completely/commit/c15d705)
-- Compare [`v0.4.3..v0.5.0`](https://github.com/bashly-framework/completely/compare/v0.4.3..v0.5.0)
+- Add docker release
+- Fix shellcheck SC2162 in the generated script
+- Fix shellcheck SC2124 in the generated script
+- Hide flag completion unless input ends with a hyphen
 
 
 v0.4.3 - 2022-07-14
 ----------------------------------------
 
-- Fix file/folder completion when they contain spaces [`9dea691`](https://github.com/bashly-framework/completely/commit/9dea691)
-- Compare [`v0.4.2..v0.4.3`](https://github.com/bashly-framework/completely/compare/v0.4.2..v0.4.3)
+- Fix file/folder completion when they contain spaces
 
 
 v0.4.2 - 2022-05-27
 ----------------------------------------
 
-- Allow keeping the test script with --keep [`20d9b15`](https://github.com/bashly-framework/completely/commit/20d9b15)
-- Compare [`v0.4.1..v0.4.2`](https://github.com/bashly-framework/completely/compare/v0.4.1..v0.4.2)
+- Allow keeping the test script with --keep
 
 
 v0.4.1 - 2022-05-21
 ----------------------------------------
 
-- Remove support for arbitrary script test to fix zsh incompatibilities [`9e3e6d9`](https://github.com/bashly-framework/completely/commit/9e3e6d9)
-- Compare [`v0.4.0..v0.4.1`](https://github.com/bashly-framework/completely/compare/v0.4.0..v0.4.1)
+- Remove support for arbitrary script test to fix zsh incompatibilities
 
 
 v0.4.0 - 2022-05-21
 ----------------------------------------
 
-- Improve template [`8172be2`](https://github.com/bashly-framework/completely/commit/8172be2)
-- Refactor CLI commands [`1fced36`](https://github.com/bashly-framework/completely/commit/1fced36)
-- Add Tester class for testing any completions script [`986f4d1`](https://github.com/bashly-framework/completely/commit/986f4d1)
-- Add tester CLI command [`09e91ee`](https://github.com/bashly-framework/completely/commit/09e91ee)
-- Add support for middle wildcard for --flag args completions [`8d25207`](https://github.com/bashly-framework/completely/commit/8d25207)
-- Add COMPLETELY_DEBUG environment setting [`44c00a1`](https://github.com/bashly-framework/completely/commit/44c00a1)
-- Allow setting the CONFIG_PATH argument via the COMPLETELY_CONFIG_PATH environment variable [`8ef65e1`](https://github.com/bashly-framework/completely/commit/8ef65e1)
-- Allow setting the SCRIPT_PATH argument via the COMPLETELY_SCRIPT_PATH environment variable [`a484ff4`](https://github.com/bashly-framework/completely/commit/a484ff4)
-- Compare [`v0.3.1..v0.4.0`](https://github.com/bashly-framework/completely/compare/v0.3.1..v0.4.0)
+- Improve template
+- Refactor CLI commands
+- Add Tester class for testing any completions script
+- Add tester CLI command
+- Add support for middle wildcard for --flag args completions
+- Add COMPLETELY_DEBUG environment setting
+- Allow setting the CONFIG_PATH argument via the COMPLETELY_CONFIG_PATH environment variable
+- Allow setting the SCRIPT_PATH argument via the COMPLETELY_SCRIPT_PATH environment variable
 
 
 v0.3.1 - 2022-02-20
 ----------------------------------------
 
-- Fix Psych 4 errors for Ruby 3.1 [`2fb9a73`](https://github.com/bashly-framework/completely/commit/2fb9a73)
-- Compare [`v0.3.0..v0.3.1`](https://github.com/bashly-framework/completely/compare/v0.3.0..v0.3.1)
+- Fix Psych 4 errors for Ruby 3.1
 
 
 v0.3.0 - 2022-01-28
 ----------------------------------------
 
-- Fix generated script for zsh compatibility [`d19369b`](https://github.com/bashly-framework/completely/commit/d19369b)
-- Compare [`v0.2.0..v0.3.0`](https://github.com/bashly-framework/completely/compare/v0.2.0..v0.3.0)
+- Fix generated script for zsh compatibility
 
 
 v0.2.0 - 2021-09-03
 ----------------------------------------
 
-- Improve generated code to support local completions [`3518434`](https://github.com/bashly-framework/completely/commit/3518434)
-- Compare [`v0.1.3..v0.2.0`](https://github.com/bashly-framework/completely/compare/v0.1.3..v0.2.0)
+- Improve generated code to support local completions
 
 
 v0.1.3 - 2021-07-21
 ----------------------------------------
 
-- Fix function name when only spaced patterns are configured [`2e14ec2`](https://github.com/bashly-framework/completely/commit/2e14ec2)
-- Compare [`v0.1.2..v0.1.3`](https://github.com/bashly-framework/completely/compare/v0.1.2..v0.1.3)
+- Fix function name when only spaced patterns are configured
 
 
 v0.1.2 - 2021-07-20
 ----------------------------------------
 
-- Add ability to generate a function that prints the script [`22de124`](https://github.com/bashly-framework/completely/commit/22de124)
-- Compare [`v0.1.1..v0.1.2`](https://github.com/bashly-framework/completely/compare/v0.1.1..v0.1.2)
+- Add ability to generate a function that prints the script
 
 
 v0.1.1 - 2021-07-20
 ----------------------------------------
 
-- Fix missing VERSION error [`e6f0ac1`](https://github.com/bashly-framework/completely/commit/e6f0ac1)
-- Compare [`v0.1.0..v0.1.1`](https://github.com/bashly-framework/completely/compare/v0.1.0..v0.1.1)
+- Fix missing VERSION error
 
 
 v0.1.0 - 2021-07-20
 ----------------------------------------
 
-- Initial version [`bcd598c`](https://github.com/bashly-framework/completely/commit/bcd598c)
-- Compare [`v0.1.0`](https://github.com/bashly-framework/completely/compare/v0.1.0)
+- Initial version
 
 
diff --git a/Dockerfile b/Dockerfile
@@ -3,6 +3,6 @@ FROM dannyben/alpine-ruby:3.3.3
 ENV PS1="\n\n>> completely \W \$ "
 WORKDIR /app
 
-RUN gem install completely --version 0.7.4
+RUN gem install completely --version 0.7.3
 
 ENTRYPOINT ["completely"]
diff --git a/README.md b/README.md
@@ -169,6 +169,13 @@ mygit:
 The `2> /dev/null` is used so that if the command is executed in a directory
 without a git repository, it will still behave as expected.
 
+### Completion scope and limitations
+
+- Completion words are treated as whitespace-delimited tokens.
+- Literal completion phrases that contain spaces are not supported as a single completion item.
+- Quotes and other special shell characters in literal completion words are not escaped automatically.
+- Dynamic `$(...)` completion commands should output plain whitespace-delimited words.
+
 ### Suggesting flag arguments
 
 Adding a `*` wildcard in the middle of a pattern can be useful for suggesting

diff --git a/lib/completely/pattern.rb b/lib/completely/pattern.rb
@@ -49,21 +49,17 @@ def compgen
       @compgen ||= compgen!
     end
 
+    def filename_action?
+      actions.include?('-A file') || actions.include?('-A directory')
+    end
+
   private
 
     def compgen!
       result = []
       result << actions.join(' ').to_s if actions.any?
-      result << %[-W "$(#{function_name} #{quoted_words.join ' '})"] if words.any?
+      result << %[-W "$(#{function_name} "#{words.join ' '}")"] if words.any?
       result.any? ? result.join(' ') : nil
     end
-
-    def quoted_words
-      @quoted_words ||= words.map { |word| %("#{escape_for_double_quotes word}") }
-    end
-
-    def escape_for_double_quotes(word)
-      word.gsub(/["\\]/, '\\\\\&')
-    end
   end
 end
diff --git a/lib/completely/templates/template.erb b/lib/completely/templates/template.erb
@@ -5,37 +5,38 @@
 # Modifying it manually is not recommended
 
 <%= function_name %>_filter() {
-  local words=("$@")
+  local words="$1"
   local cur=${COMP_WORDS[COMP_CWORD]}
   local result=()
-  local want_options=0
 
   # words the user already typed (excluding the command itself)
   local used=()
   if ((COMP_CWORD > 1)); then
     used=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")
   fi
 
-  # Completing an option: offer everything.
-  # Completing a non-option: drop options and already-used words.
-  [[ "${cur:0:1}" == "-" ]] && want_options=1
-  for word in "${words[@]}"; do
-    if ((!want_options)); then
+  if [[ "${cur:0:1}" == "-" ]]; then
+    # Completing an option: offer everything (including options)
+    echo "$words"
+
+  else
+    # Completing a non-option: offer only non-options,
+    # and don't re-offer ones already used earlier in the line.
+    for word in $words; do
       [[ "${word:0:1}" == "-" ]] && continue
 
+      local seen=0
       for u in "${used[@]}"; do
         if [[ "$u" == "$word" ]]; then
-          continue 2
+          seen=1
+          break
         fi
       done
-    fi
-
-    # compgen -W expects shell-escaped words in one space-delimited string.
-    printf -v word '%q' "$word"
-    result+=("$word")
-  done
+      ((!seen)) && result+=("$word")
+    done
 
-  echo "${result[*]}"
+    echo "${result[*]}"
+  fi
 }
 
 <%= function_name %>() {
@@ -59,6 +60,9 @@
 % patterns.each do |pattern|
 % next if pattern.empty?
     <%= pattern.case_string %>)
+% if pattern.filename_action?
+      compopt -o filenames 2>/dev/null
+% end
       while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen <%= pattern.compgen %> -- "$cur")
       ;;
 

diff --git a/lib/completely/version.rb b/lib/completely/version.rb
@@ -1,3 +1,3 @@
 module Completely
-  VERSION = '0.7.4'
+  VERSION = '0.7.3'
 end