I’m just starting to give restic a try, using the precompiled binary on debian stretch.
I’d like to setup the zsh completion and the manpages in the “proper way”, and have noticed there is a generate subcommand.
However I couldn’t find an explanation somewhere on how to use it properly. The “manual” page on readthedocs was not up-to-date (still lists the outdated autocomplete command, I’ve opened a PR for that), and there is no documentation about using the generate command.
I have googled and it seems that additional manpages (that is, not managed by the package management system) should go to /usr/local/share/man/man1/ (https://askubuntu.com/a/244810/726323), but I don’t really know how to proceed for the completion files.
Can someone explain how the generate command is meant to be used?
Please know that the version of restic contained in stretch (0.3.3) is very old. Most of what I’m going to write in the remainder of this message does not apply to this old version.
The generate command can be used to generate man pages, zsh and bash completion files. The manpages should be already installed by your distribution. If you want to generate the files yourself, have a look at the help for the generate command:
$ restic generate --help
The "generate" command writes automatically generated files like the man pages
and the auto-completion files for bash and zsh).
Usage:
restic generate [command] [flags]
Flags:
--bash-completion file write bash completion file
-h, --help help for generate
--man directory write man pages to directory
--zsh-completion file write zsh completion file
So you can run: restic generate --man /tmp/restic-manpages --zsh /tmp/_restic.zsh --bash /tmp/_restic.bash to save the manpages and auto-completion files to /tmp/.
The main functionality of the generate command is implemented by the CLI framework we’re using, cobra, and it seems the zsh auto completion is not very advanced.
Indeed I know that the version in Debian is outdated (it wouldn’t be Debian otherwise ^^), this is why I mentioned that I’m using the precompiled binary released on GitHub, and not the package from the distribution.
As such, I don’t have the help of the package manager for deploying the manpages and the completion files at the “proper” place. And naturally I don’t want to manually put generated files in locations which are meant for being managed by the package manager (for example /usr/share/man).
This is why I was wondering where should the generated files go so that they are found by man, bash and zsh respectively while at the same time not conflict with the locations managed by the package manager.
In your reply you mention /tmp but that’s obviously not the “proper” location to place the generated files in a user use-case.
I was actually about to make a PR for the missing doc in https://github.com/restic/restic/blob/master/doc/020_installation.rst due to the new generate command.
Since restic autocomplete is removed and restic generate introduced this information is outdated and should be updated at some point.
I am a little bit hesitant to make a PR for that. I was expecting restic to detect what shell I am using and generate the autocompletion files based on the shell in its default directory, if not specified otherwise.
But what I am seing is that you have to specify everything explicitly; what and where you want to save the autocompletion or man pages files.
Did you mean to have it be manual or could there be a possibility of discussion for the introduction of a detection for what shell the autocompletion files should be generated - as well as the man pages.
The usual way how shell completion for commands work is that there’s a dir with many files that the shell sources either at startup or on demand. At the moment, the generate command is meant to be used once to generate the files (auto completion and man pages) so that they can be put into the right location, either by the user or by a packager.
It seems to me that you may have a slightly different idea on how that should work, would you mind to elaborate a bit?
Ok maybe I was misunderstanding or not clear enough in my wording, sorry about that.
So I thought the restic generate command can be called without any additional flags.
But right now, at least in 0.8.0, you have to specify flags for either bash, zsh or the man pages and the destination of the generated files.
So what I was trying to say yesterday was: Should restic generate be able to work without any additional flags or do we, the user, have to find out where we need to put the files we want to generate ourselves.
Like you said, I know that for bash I can configure it in my bash profile file and have it source those directories.
But wouldn’t it in a default state try to go to /etc/bash_completion.d/ first to check for scripts there?
Same for man pages; how would I know where to put man pages for a program?
Maybe I am expecting more of the command than it was intended for but my assumption was that it would but the necessary files in the right folders for me. IF I don’t specify otherwise using the flags for the generate command. Does this make more sense now?
Just a user here so I’ll let the devs answer what they think, but I’m afraid that’s not a simple task since there is so many distros with different choices for where to place the completion files and the manpages.
In the case of a package install, the issue is solved because that’s the task of the maintainer of the package to provide and place the manpages and stuff at the right place.
But this thread is about the manual install case, and my initial question was to document where the generated files should go in that case.
For the bash completion, I would agree that /etc/bash_completion.d/ is probably the correct choice for distros following that convention.
But for manpages, that’s not so evident, since for example /usr/share/man is meant to be managed by the package manager and not altered manually. Thus the question: Where should I put it then? The only answer for now mentioned /tmp which is clearly not the expected one.
TL;DR:
I don’t think it would be good idea to try to implement the generate command such that it places the files automatically.
Instead I suggest adding some pieces of advice into the documentation about which paths are recommended (with maybe different paths for different distros).
I’m afraid that it’s the latter: You need to find out where to put the files, restic cannot do that for you due to the sheer number of different platforms and/or distributions.
Yes, thanks for the explanation. The generate command is meant to be used by packagers and admins to generate the files, which are then need to be placed into the correct folders. For man pages, even further work (like compressing the files) may be necessary, depending on the OS/distribution. Typically, programs do not (and can not) decide on their own where to put those files.
I experienced the same feel of uncertainty in adding the man pages. This was the only hit Google gave me on restic specifically. Therefore, I decided to share my learning for others.
“manpath” will tell you the locations currently configured for the man page locations. You change those in configuration files but that is another story. My Ubuntu tells me:
I picked /usr/local/man the /usr/local/ hierarchy is intended for using when installing software manually by the administrators. (linuxfoundation) It should be safe from being overwritten by the package managers.
To be exact, I discovered that the manual pages restic generate --man creates need to be placed in a subfolder man1 according to the categorization of the man-pages. Invoking (sudo) mandb will update the database indexes so that the man pages for the restic will be discovered by man.
I fully agree that the documentation should suggest and guide more. The official repositories do contain old versions and installing the precompiled binaries is an easy short cut for many users.
For bash the description is fine. But for zsh it is sill unclear where to put the generated autocomplete files. Maybe integrate it with oh-my-zsh?
Where did you put it?
source this generated file source ~/my-dotfiles/zsh_custom/restic-comletion.zsh wherever you have your custom setup. I have ZSH_CUSTOM=~/zsh_custom so I have my stuff under ~/zsh_custom/plugins/.... Or you can source it directly from your ~/.zshrc
It is possible to debug the completion by export BASH_COMP_DEBUG_FILE=~/mydebug.txt before using completion. In some other terminal you can run tail -f ~/mydebug.txt in parallel and observe what happens.