fix: miscellaneous fixes after separation of directories #1536

akinomyoga · 2025-12-31T10:16:00Z

I described the details in the respective commit messages.

yedayak · 2025-12-31T10:44:49Z

README.md

-     its usage is no longer recommended, is `compatdir` (get it with
-     `pkg-config --variable=compatdir bash-completion`). From this
+     completions for more than one command. The completion filename for command
+     `foo` in this directory should be `foo.bash`.  Unsuffixed `foo` also


nit: Remove double space after period, there are some more

Suggested change

`foo` in this directory should be `foo.bash`. Unsuffixed `foo` also

`foo` in this directory should be `foo.bash`. Unsuffixed `foo` also

Hmm, is there a specific preference or a rule for double-space sentence separators? The double-space style is the tradition in typewriters, while a single space is more typical in modern text files.

The problem is that I use GNU Emacs, and GNU Emacs recognizes "a period plus double spaces" as the sentence terminator, while "a period plus a space" is treated as a period after an abbreviation (like Mr., Inc., Rev., etc), following the convention in typewriters. If the sentence-end double spaces are converted to single spaces, it affects the behavior of the auto line breaking at column 79. I don't want to manually convert all single spaces at the end of sentences to double spaces and convert back double spaces to single spaces every time I edit a paragraph and adjust line breaking.

As far as I look at the codebase, both styles are mixed. @scop also seems to use the double-space style (though I'm not sure about its frequency compared to that of the single-space style). For example, the message in the deprecated files # Use of this file is deprecated. Upstream completion is available in (with double spaces) was introduced by @scop in e.g. 861be75.

I don't have really have a specific preference, I'm just used to the single space. It's fine to leave it likes this

Actually, I've noticed this issue too, though I have never raised it in a discussion. It's a subtle issue about the conflict between the modern style and the text editor behavior, so I haven't tried to normalize the style either way. If both of you are fine with it, let me just leave it as is until an actual issue occurs.

I'm a long time Emacs user as well, and have had the habit of using two for ages, but I'm not paying that much attention to it these days, as not doing so does not interfere with anything I routinely do. So either style is fine with me, but I'd prefer consistency and even better if there's a linter or something that whines about the "wrong" one. Flagging double is quite a bit easier to implement if one wants to write one, and some are in existence already, for example https://github.com/Automattic/harper advises against using "French spaces" (i.e. the double ones).

README.md

We have separated "helpers" and "helpers-dist", but we actually have not documented that third party may install helper scripts in the directory exposed through the pkg-config variable `helpersdir`. We mention it in README. The background for this change is found in the following discussion: scop#1329 (reply in thread) > I suppose the same consideration applies to the helpers dir, > i.e. we'd have helpers-dist? scop#1329 (reply in thread) > Has helpers been suggested as a place for external packages to put > files? I didn't know that, but I've now realized that we've been > exposing helpersdir in bash-completion.pc.in, but it's not mentioned > elsewhere. > > [...] > > Mention the pkg-config variable `helpersdir` in `README`. Co-authored-by: Yedaya Katsman <yedaya.ka@gmail.com>

* fix(_comp_load): "completions/<cmd>.bash" has a higher priority than "completions/<cmd>"

As described in README.md, "completions/_<cmd>" are reserved names for the bash-completion project, so external completions are supposed not to use these names. Since we moved our fallback/compat completions into "completions-fallback" directory, the support for "_<cmd>" should be safely removed.

This implements the suggestion by Yedaya Katsman <yedaya.ka@gmail.com> [1] to put README explaining the directory structure: > [...] it might hurt discoverability of where completions are coming > from a bit. Maybe adding a README file that points to the default > completions will be nice. [1] \ scop#1329 (reply in thread)

This moves the in-tree completion for interdiff to completions-fallback. The upstream patchutil-0.4.3 has started to offer completion files as reported in Ref. [1]. [1] scop#1502

scop

Some suggestions in comments.

The commit noting removal of support for underscored files is marked as a breaking change. This means release-please will likely bump the next version to 3.x. I'm not sure if we want that, and there's some wiggle room as it support for underscore prefixed ones was already marked for internal use only, so I guess we could just drop the exclamation mark from the message.

scop · 2026-01-02T15:35:57Z

completions/README.md

+This directory `completions` is the place to put **third-party completion
+files** that are loaded by


Maybe clarify here (and in helpers) what we mean by "third party". There's also a mention of "external" in the note below. How about something like this to unify the terms?

Suggested change

This directory `completions` is the place to put **third-party completion

files** that are loaded by

This directory, `completions`, is the place to put "external" completion files,

i.e. ones not shipped by the bash-completion project itself.

They are loaded by

scop · 2026-01-02T15:36:29Z

completions/README.md

+> The core `bash-completion` framework (<= 2.17) has provided also *completion
+> files bundled with the bash-completion framework itself* in this directory,
+> but we separated those files into `completions-core` and
+> `completions-fallback`.  However, external completion provider should


Suggested change

> `completions-fallback`. However, external completion provider should

> `completions-fallback`. However, external completion providers should

scop · 2026-01-02T15:36:46Z

completions/README.md

+> `completions-fallback`.  However, external completion provider should
+> continue to install their completion files in `completions`.  The new
+> directories `completions-core` and `completions-fallback` are internal
+> directories intended to be used by the core `bash-completion`.


Suggested change

> directories intended to be used by the core `bash-completion`.

> directories intended to be used by the core bash-completion only.

scop · 2026-01-02T15:37:29Z

completions/README.md

+> directories intended to be used by the core `bash-completion`.
+
+The programmable completion for the command `<cmd>` is supposed to be provided
+as the file `completions/<cmd>.bash`.  The implementation examples are found in


Suggested change

as the file `completions/<cmd>.bash`. The implementation examples are found in

in the file `completions/<cmd>.bash`. The implementation examples are found in

scop · 2026-01-02T15:38:00Z

completions/README.md

+`completions-core`, which uses the latest bash-completion API (v3).  If you
+want to make the completion file to work also with an older version of
+`bash-completion`, you need to use the previous API of v2, which is contiuned
+to be supported.  For examples with API v2, please reference the completion


Suggested change

to be supported. For examples with API v2, please reference the completion

to be supported for now. For examples with API v2, please reference the completion

scop · 2026-01-02T15:38:39Z

helpers/README.md

Suggesting similar changes here as in completions/README.md above.

scop · 2026-01-02T15:39:44Z

README.md

+     `foo` in this directory should be `foo.bash`.  Unsuffixed `foo` also
+     works, but it is deprecated in >= 2.18.
+   - Helper scripts used by completions may be placed in the directory
+     `<helpersdir>`, which can be retrieved with `pkg-config


Not related to this particular line, but the first commit message refers to helpers-dist -> should change that to helpers-core.

akinomyoga force-pushed the sepdir-3 branch from 64fe877 to 670e79e Compare December 31, 2025 13:21

yedayak reviewed Dec 31, 2025

View reviewed changes

akinomyoga force-pushed the sepdir-3 branch from 670e79e to fb0c974 Compare December 31, 2025 14:28

akinomyoga and others added 5 commits December 31, 2025 23:29

fix(_comp_load): deprecate unsuffixed "completions/<cmd>" w/o ".bash"

43ca26b

* fix(_comp_load): "completions/<cmd>.bash" has a higher priority than "completions/<cmd>"

fix(interdiff): move to fallback for the upstream completion

48d41cd

This moves the in-tree completion for interdiff to completions-fallback. The upstream patchutil-0.4.3 has started to offer completion files as reported in Ref. [1]. [1] scop#1502

akinomyoga force-pushed the sepdir-3 branch from fb0c974 to 48d41cd Compare December 31, 2025 14:29

scop requested changes Jan 2, 2026

View reviewed changes

	`foo` in this directory should be `foo.bash`. Unsuffixed `foo` also
	`foo` in this directory should be `foo.bash`. Unsuffixed `foo` also

		This directory `completions` is the place to put **third-party completion
		files** that are loaded by

-This directory `completions` is the place to put **third-party completion
-files** that are loaded by
+This directory, `completions`, is the place to put "external" completion files,
+i.e. ones not shipped by the bash-completion project itself.
+They are loaded by

	> `completions-fallback`. However, external completion provider should
	> `completions-fallback`. However, external completion providers should

	> directories intended to be used by the core `bash-completion`.
	> directories intended to be used by the core bash-completion only.

	as the file `completions/<cmd>.bash`. The implementation examples are found in
	in the file `completions/<cmd>.bash`. The implementation examples are found in

	to be supported. For examples with API v2, please reference the completion
	to be supported for now. For examples with API v2, please reference the completion

fix: miscellaneous fixes after separation of directories #1536

Are you sure you want to change the base?

fix: miscellaneous fixes after separation of directories #1536

Conversation

akinomyoga commented Dec 31, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

scop left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants