Preserving manual order in ABBR_USER_ABBREVIATIONS_FILE

[5A6F65]

I consider ABBR_USER_ABBREVIATIONS_FILE more of a configuration file than just a persistence store.
It would be more readable if abbreviations could be categorized rather than strictly sorted alphabetically. In fact, alphabetical order offers no real benefit.
The following two configurations load with almost identical performance, but the first is more readable:

abbr 'git cm'='git commit -v%'
abbr 'git ca'='git commit -v --amend%'

abbr 'git cl'='git clone'

abbr 'git ca'='git commit -v --amend%'
abbr 'git cl'='git clone'
abbr 'git cm'='git commit -v%'

Currently, we can achieve this by manually editing the file. However, whenever I add, erase, or rename an abbreviation via the abbr command in the terminal, ABBR_USER_ABBREVIATIONS_FILE is automatically re-sorted.
Would it be a good idea to introduce a configuration variable (defaulting to off) that prevents wholesale reordering on changes—instead, re‑parsing and updating only the affected line?
Parsing does introduce a performance overhead, but it only occurs when abbreviations change and is minimal, so I believe it’s entirely acceptable.

By the way, I noticed that in the configuration-variables page, the “Storage and manual editing” link under ABBR_AUTOLOAD and ABBR_USER_ABBREVIATIONS_FILE points to configuration-variables.html#storage-and-manual-editing, but it should actually point to storage-and-manual-editing.html.

[olets]

Thanks for the suggestion! I agree that manual grouping and comments could be useful. But preserving order, comments, and/or line breaks will almost certainly not happen.

A fundamental part of zsh-abbr's design is that the user abbreviations file is read into an array and rewritten from the array. Changing that model would require a very significant —possibly full— rewrite.

Going through an array means losing comments and line breaks.

zsh doesn't guarantee any particular order in arrays, so we can't preserve order.

In theory we could provide an option for not sorting alphabetically, but the order would instead be arbitrary and could change every time zsh-abbr writes to the file (which it does as part of many of the CLI commands).

//

The bad links is a great catch. Other links in that table are outdated too. A PR to the docs site would be very welcome.

[5A6F65]

To preserve order, comments, and/or line breaks, my idea is to parse ABBR_USER_ABBREVIATIONS_FILE and pinpoint exactly which lines define the abbreviations that need changes.
Then, whenever the configuration is updated, we only rewrite those target lines—leaving the rest of the file, including comments and blank lines, completely untouched.
This approach would require a totally different code path from the current implementation; perhaps it could be listed as a future enhancement?

[olets]

perhaps it could be listed as a future enhancement?

It's unlikely that this will ever make it onto the zsh-abbr road map.

[5A6F65]

Please allow me to share the solution I am currently using.

I group my abbreviations by command and store them under ${XDG_CONFIG_HOME:-$HOME/.config}/zsh-abbr. The directory structure looks like this:

zsh-abbr
├── commands
│   ├── cmd1
│   ├── cmd2
│   └── cmd3
└── misc

For example, commands/git is used to store abbreviations related to git.
Meanwhile, misc is for small and scattered abbreviations that are not worth creating a dedicated group for, such as:

abbr 'al'='abbr load%'
abbr 'cc'='clear && cat'

Then, before loading zsh-abbr, I run the following:

() {
    local abbr_cache_dir abbr_cache_file
    local abbr_config_dir abbr_config_file
    local -a abbr_config_files

    abbr_config_dir=${XDG_CONFIG_HOME:-$HOME/.config}/zsh-abbr
    abbr_cache_dir=${XDG_DATA_HOME:-$HOME/.local/share}/zsh-abbr
    abbr_cache_file=$abbr_cache_dir/current
    [[ -d $abbr_config_dir ]] || return
    [[ -d $abbr_cache_dir ]] || mkdir -p $abbr_cache_dir || return
    [[ ! -f $abbr_cache_file ]] || : >| $abbr_cache_file || return

    abbr_config_files=()
    for abbr_config_file ($abbr_config_dir/commands/*(N)) {
        (( ${+commands[${abbr_config_file:t}]} )) || continue
        abbr_config_files+=($abbr_config_file)
    }
    abbr_config_files+=($abbr_config_dir/misc)

    for abbr_config_file ($abbr_config_files) {
        [[ -f $abbr_config_file && -r $abbr_config_file ]] || continue
        <$abbr_config_file
        print
    } >> $abbr_cache_file

    ABBR_USER_ABBREVIATIONS_FILE=$abbr_cache_file
    return 0
}

It merges the abbreviations for all commands that exist in the $PATH into ${XDG_DATA_HOME:-$HOME/.local/share}/zsh-abbr/current.
This introduces some additional IO overhead, but for me it is worth it.