Borg: Officially maintain/include autocompletion
IMHO autocompletion for mayor shells (zsh, bash) is a feature each good linux tool should have. And it should be maintained officially in this repo and included in it, because then packagers rather see it and can be assured that support for it won't be dropped easily.
Maybe put it in some doc or misc dir.
This issue means include
https://github.com/mrkmg/borgbackup-zsh-completion into this repo (& update it) and include https://github.com/borgbackup/borg/issues/1782 here.
rugk
All 37 comments
@rugk there are quite some different shells out there, so having this packaged/maintained separately seems to be easier for me.
ThomasWaldmann
on 23 Jul 2017
Mhh, then maybe at least maintain/include them in the official BorgBackup organisation in contrast to "just some community scripts/things". Maybe make a "shell-autocompletion" repo, where all these can be maintained.
rugk
on 23 Jul 2017
I can do that if at least 2 maintainers of shell completion projects show interest in that.
Alternatively, they could also get linked from the community repo's link list.
ThomasWaldmann
on 23 Jul 2017
If @mrkmg and maybe someone solving https://github.com/borgbackup/borg/issues/1782 show interest we have already two people.
rugk
on 23 Jul 2017
I am willing to maintain the zsh auto-completion. I use borg daily, although I would probably need to be alerted to flag changes as my use is fairly regular and consistent.
As for bash, I do not use bash nor do I have a good understanding of how to setup auto-completion for it.
mrkmg
on 23 Jul 2017
So I've suggested the Debian package maintainer to include the borg autocompletion scripts in the package. (bug https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=869381) and the reply was:
I really prefer to see them merged upstream before applying them.
please upstream them and ping back, thanks!
So I think that's another argument for "merging" – or at least moving them to the borgbackup organisation. So, at least, currently, the zsh auto-completion could be maintained…
rugk
on 25 Jul 2017
There is also a request on the fedora side from @rugk :
https://bugzilla.redhat.com/show_bug.cgi?id=1473973
I would package and maintain a seperate package for fedora (or in the same if its merged to the main repo), but I think it should be maintained by one maintainer/project, preferable the borgbackup project, instead of each distro reinventing the autocompletion-wheel.
bpereto
on 29 Jul 2017
OK, so the main point of putting autocompletion code into the main borg repo would be easy correlation (a borg release would also contain matching autocompletion code). While this can be also managed when it lives in another repo (at maintainer, other in borg organisation), it would need a bit more management effort then.
ThomasWaldmann
on 29 Jul 2017
As this won't touch borg code and is just a separate file or directory, we could add it to 1.0-maint and 1.1-maint (assuming someone maintains it for 1.0.x and 1.1.x).
Place?
misc/completion/<shell>/...scripts/completion/<shell>/...(is shell autocompletion stuff a script or rather a config file?)
ThomasWaldmann
on 29 Jul 2017
script.
To me it looks like it'd be wiser to generate these automatically, not maintain by hand.
enkore
on 29 Jul 2017
BTW, I'ld appreciate if such stuff is licensed under same license as borg, just to keep extra license files and having to refer to them to a minimum.
ThomasWaldmann
on 29 Jul 2017
Can we get all the autocompletion maintainer get together here?
Everybody speak up, include the shell you maintain borg completions for and the borg version you made the completions for.
ThomasWaldmann
on 4 Oct 2017
Also, the POV from package maintainers would be interesting if the completions should come with the tool or with the shell.
ThomasWaldmann
on 4 Oct 2017
I don't maintain fish-shell, but I'm willing to maintain fish completions for borg.
I wrote completions for borg 1.0.11.
My POV: Well, fish shell does ship lots of completions for foreign programs, but the problem with that is the huge difference in quality. Some completions are great, are maintained, some just old and poorly written. My 2cents go for tool, it is the borg developers who know when and how to update the completions in any shell. So I think Borg could carry fish completions.
The place could indeed be scripts/completion/<shell>/...
update: completions for borg 1.1 are ready.
SanskritFritz
on 4 Oct 2017
@bpereto your offer to maintain the zsh version is still valid? If so we already have two shells.
Maybe that's a good start.
rugk
on 5 Oct 2017
What I meant was :
I would package and maintain a seperate package for fedora
and I will still package the autocompletition, if its maintained by the borg project.
bpereto
on 10 Oct 2017
@mrkmg, you were the one who created the zsh completions in #1328. Would you still maintain it if it became part of borg?
SanskritFritz
on 10 Oct 2017
I totally want to. I have been VERY busy at as of late, but I will strive to update the definitions I have at my repo to the latest version asap to get the ball rolling.
mrkmg
on 12 Oct 2017
Great 😄
All we need now is someone creating and maintaining bash completions?
SanskritFritz
on 12 Oct 2017
I have a question.
Is the order of the options restricted to borg [common options] COMMAND [command options] REPO
Or can the repo come before the command options, or common options after the command?
mrkmg
on 13 Oct 2017
So, I have updated the version I have to work for 1.1.0 at my repo.
https://github.com/mrkmg/borgbackup-zsh-completion
I have been staring at this file for like 4 hours, so if I could have someone check that there are no typos that would be awesome!
mrkmg
on 13 Oct 2017
I looked at it for some time and it looks quite good apart from that I don't see the archives completion in the new version. Any other problems I find I'll open an issue report on your repo.
I filed an issue regarding the previous version you had, did you see it?
SanskritFritz
on 13 Oct 2017
Yeah, I totally forgot to re-add that. Working on it now
mrkmg
on 13 Oct 2017
Is the order of the options restricted to borg [common options] COMMAND [command options] REPO
No, they can be anywhere, I routinely use the options after the repo::archive.
SanskritFritz
on 13 Oct 2017
Hey @SanskritFritz I have re-added in the archive completion, and it should work when BORG_REPO is exported now as well.
mrkmg
on 16 Oct 2017
Cool!
Maybe later I'll test it as well, but I never used zsh, so...
SanskritFritz
on 16 Oct 2017
@mrkmg Please update zsh completions for borg 1.1.1
I have created bash completions and am ready to make a pull request. My question is, should I include your file into the PR or do you want to make one separately?
I plan to put the files into borg/scripts/shell_completions.
UPDATE: I just found a major problem with the bash completion file, I'll have to rewrite part of it.
SanskritFritz
on 1 Nov 2017
I have updated the completions on my repo.
I can make a pull request. What should I name my completion file? The ZSH standard for completion files is _{command}, so for borg is would expect it to be named _borg.
borg/scripts/shell_completions/{what}
mrkmg
on 3 Nov 2017
borg/scripts/shell_completions/{name_of_shell}/...
ThomasWaldmann
on 3 Nov 2017
Yeah, this is how I planned to do it, so just follow this schema:
https://github.com/SanskritFritz/borg/tree/master/scripts/shell_completions
SanskritFritz
on 3 Nov 2017
fixed by #3268 and #3269, thanks!
ThomasWaldmann
on 4 Nov 2017
@ThomasWaldmann One question:
As I prepare the shell completions scripts for the next borg version, I skim through the documentation to see what options or commands have been added, removed or changed (since the structure of the scripts closely follow the layout of the docs). You said the docs are autogenerated from the source, so I'd like to know when is the right time to do my checks. I other words how do I know the docs have been autogenerated for borgbackup.readthedocs.io?
SanskritFritz
on 13 Nov 2017
Until now, I usually ran python setup.py build_usage (and also build_man) at release time.
But if you want to look at uptodate docs early, maybe just locally running that whenever you have time is easiest (and looking at the locally built docs or the diff).
ThomasWaldmann
on 13 Nov 2017
That is great, thanks. Another important question is, how do I know about an upcoming release? I need to make sure that the new release of borg includes the matching completions.
SanskritFritz
on 13 Nov 2017
Almost every release has a release candidate
enkore
on 14 Nov 2017
Almost every release has a release candidate
enkore
on 14 Nov 2017
Best is maybe to watch the milestones.
Also, maybe regularly update the stuff, so most will be correct then anyway.
ThomasWaldmann
on 14 Nov 2017
Related issues
tconstans
·
5Comments
anarcat
·
4Comments
rugk
·
3Comments
rugk
·
4Comments
ypid
·
6Comments
Most helpful comment
OK, so the main point of putting autocompletion code into the main borg repo would be easy correlation (a borg release would also contain matching autocompletion code). While this can be also managed when it lives in another repo (at maintainer, other in borg organisation), it would need a bit more management effort then.