Re: [PATCH] Document colonless numeric history expansion word designators

[Éric NICOLAS <ccjmne@xxxxxxxxx>]

Following up on this documentation patch.  Could someone review whether
documenting the existing colonless numeric word-designator behaviour is
acceptable?

The patch includes the implementation-history reference and regression test.
If there’s a concern about treating this behaviour as supported, I’d
appreciate knowing that too.

You can find the patch in question at: https://zsh.org/workers/55134

Thanks.

On Sun, 6 Sept 2026 at 19:12, Éric NICOLAS <ccjmne@xxxxxxxxx> wrote:
>
> Using history expansion, the implementation of Zsh allows the omission
> of the colon before some numeric word designators, following:
>
>     !!, !#, and !?str?, for example !!2, !#1, and !?test?4:t.
>
> The implementation has been exhibiting that behaviour since the earliest
> revision in this Git repository, with e74702b46 (Initial revision,
> 1999-04-15), but the manual currently says that the colon may only be
> omitted before:
>
>     ^, $, *, -, or %.
>
> For example, you may very well do:
>
>     mkdir /tmp/asdf && cd !#1
>
> Document the long-standing behaviour and introduce test coverage.
>
> ---
> I wrote to the zsh-users mailing list in April this year, asking for
> confirmation this behaviour is intended and here to stay.
>
> This patch proposes to document that behaviour, which has been in place
> throughout the entire recorded history of Zsh's source.
>
> For reference, here's my thread: https://www.zsh.org/mla/users/2026/msg00148.html
> ---
>  Doc/Zsh/expn.yo      |  7 +++++--
>  Test/W01history.ztst | 14 ++++++++++++++
>  2 files changed, 19 insertions(+), 2 deletions(-)
>
> diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
> index c5995f4e4..86edcddd0 100644
> --- a/Doc/Zsh/expn.yo
> +++ b/Doc/Zsh/expn.yo
> @@ -184,8 +184,11 @@ cindex(word designators, history)
>  A word designator indicates which word or words of a given command line are
>  to be included in a history reference.  A `tt(:)' usually
>  separates the event specification from the word designator.
> -It may be omitted only if the word designator begins with a
> -`tt(^)', `tt($)', `tt(*)', `tt(-)' or `tt(%)'.
> +It may be omitted if the word designator begins with a `tt(^)', `tt($)',
> +`tt(*)', `tt(-)' or `tt(%)'.  A numeric word designator may also omit the colon
> +after `tt(!!)', `tt(!#)', or a `tt(!?)var(str)tt(?)' event designator, for
> +example `tt(!!3)', `tt(!#3)' or `tt(!?)var(str)tt(?3)'.  Note that `tt(!3)'
> +refers to event 3 rather than word 3 of the previous event.
>  Word designators include:
>
>  startsitem()
> diff --git a/Test/W01history.ztst b/Test/W01history.ztst
> index 665a37f2c..272b5a435 100644
> --- a/Test/W01history.ztst
> +++ b/Test/W01history.ztst
> @@ -18,6 +18,20 @@
>  >one two three four five six seven eight nine ten
>  >print one two three four five six seven eight nine ten one two
>
> +  PS1= $ZTST_testdir/../Src/zsh -fis <<<'
> +    print huey dewey louie
> +    print !!2
> +    print /tmp/asdf !#1
> +    print test a/one b/two c/three
> +    print !?test?4:t
> +  '
> +0:Numeric word references without a colon
> +>huey dewey louie
> +>dewey
> +>/tmp/asdf /tmp/asdf
> +>test a/one b/two c/three
> +>three
> +
>    PS1= $ZTST_testdir/../Src/zsh -fis <<<'
>      print line one of an arbitrary series
>      print issue two for some mystery sequence
> --
> 2.55.0
>


-- 
Eric NICOLAS