From f1ce8c0e8a4b61b9497864017bd193493bd1ec1d Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Thu, 3 Mar 2022 22:31:11 +0530 Subject: [PATCH] Add some docs for the ssh kitten --- docs/conf.py | 7 ++++ docs/faq.rst | 2 +- docs/kittens/ssh.rst | 65 +++++++++++++++++++++++++++++++ docs/kittens_intro.rst | 1 + kittens/ssh/main.py | 3 ++ kittens/ssh/options/definition.py | 27 ++++++++++++- kitty/conf/types.py | 1 + 7 files changed, 104 insertions(+), 2 deletions(-) create mode 100644 docs/kittens/ssh.rst diff --git a/docs/conf.py b/docs/conf.py index a0f8e0ad1..d02e347b4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -200,6 +200,13 @@ def commit_role( def write_cli_docs(all_kitten_names: Iterable[str]) -> None: from kitty.cli import option_spec_as_rst from kitty.launch import options_spec as launch_options_spec + from kittens.ssh.copy import option_text + from kittens.ssh.options.definition import copy_message + with open('generated/ssh-copy.rst', 'w') as f: + f.write(option_spec_as_rst( + appname='copy', ospec=option_text, heading_char='^', + usage='file-or-dir-to-copy ...', message=copy_message + )) with open('generated/launch.rst', 'w') as f: f.write(option_spec_as_rst( appname='launch', ospec=launch_options_spec, heading_char='_', diff --git a/docs/faq.rst b/docs/faq.rst index f15a6e517..fab33dd25 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -46,7 +46,7 @@ terminfo files to the server:: kitty +kitten ssh myserver -This ssh kitten takes all the same command line arguments +This :doc:`ssh kitten ` takes all the same command line arguments as ssh, you can alias it to something small in your shell's rc files to avoid having to type it each time:: diff --git a/docs/kittens/ssh.rst b/docs/kittens/ssh.rst new file mode 100644 index 000000000..34f6952f4 --- /dev/null +++ b/docs/kittens/ssh.rst @@ -0,0 +1,65 @@ +Truly convenient SSH +========================================= + +The ssh kitten allows you to login easily to remote servers, and automatically +setup the environment there to be as comfortable as your local shell. You +can specify environment variables to set on the remote server and +files to copy there, making your remote experience just like your +local shell. Additionally, it automatically sets up :ref:`shell_integration` on +the remote server and copies the kitty terminfo database there. + +The ssh kitten is a thin wrapper around the traditional `ssh `__ +command line program and supports all the same options and arguments and configuration. +In most scenarios it is in fact a drop in replacement for ``ssh``. To try it +out, simply run: + +.. code-block:: sh + + kitty +kitten ssh some-hostname-to-connect-to + +You should end up at a shell prompt on the remote server, with shell +integration enabled. If you like it you can add an alias to it in you shell's +rc files: + +.. code-block:: sh + + alias s=kitty +kitten ssh + +So you can now type just ``s hostname`` to connect. + +The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf` +file where you can specify environment variables to set on the remote server +and files to copy from your local machine to the remote server. Let's see a +quick example: + +.. code-block:: conf + + # Copy the files and directories needed to setup some common tools + copy .zshrc .vimrc .vim + # Setup some environment variables + env SOME_VAR=x + # COPIED_VAR will have the same value on the remote server as it does locally + env COPIED_VAR=_kitty_copy_env_var_ + + # Create some per hostname settings + hostname *.myservers.net + copy env-files + env SOMETHING=else + + hostname somehost.org + copy --dest=foo/bar some-file + copy --glob some/files.* + + +See below for full details on the syntax and options of :file:`ssh.conf`. + + +.. include:: /generated/conf-kitten-ssh.rst + + +.. _ssh_copy_command: + +The copy command +-------------------- + +.. include:: /generated/ssh-copy.rst diff --git a/docs/kittens_intro.rst b/docs/kittens_intro.rst index f99feccd1..6eb773176 100644 --- a/docs/kittens_intro.rst +++ b/docs/kittens_intro.rst @@ -15,6 +15,7 @@ Extend with kittens kittens/remote_file kittens/hyperlinked_grep kittens/transfer + kittens/ssh kittens/custom kittens/* diff --git a/kittens/ssh/main.py b/kittens/ssh/main.py index 6e8cc2a65..bd5741baf 100644 --- a/kittens/ssh/main.py +++ b/kittens/ssh/main.py @@ -357,3 +357,6 @@ if __name__ == '__main__': main(sys.argv) elif __name__ == '__completer__': setattr(sys, 'kitten_completer', complete) +elif __name__ == '__conf__': + from .options.definition import definition + sys.options_definition = definition # type: ignore diff --git a/kittens/ssh/options/definition.py b/kittens/ssh/options/definition.py index 2c3b29c1e..165555627 100644 --- a/kittens/ssh/options/definition.py +++ b/kittens/ssh/options/definition.py @@ -7,6 +7,12 @@ from kitty.conf.types import Definition +copy_message = '''\ +Copy files and directories from the local computer to the remote one. The +specified files are assumed to be relative to the HOME directory and copied +to the HOME on the server. Directories are copied recursively. If absolute paths +are used, they are copied as is.''' + definition = Definition( 'kittens.ssh', ) @@ -26,7 +32,26 @@ against is the hostname used by the remote computer, not the name you pass to SSH to connect to it. ''') -opt('+copy', '', option_type='copy', add_to_default=False, long_text=''' +opt('+copy', '', option_type='copy', add_to_default=False, long_text=f''' +{copy_message} For example:: + + copy .vimrc .zshrc .config/some-dir + +If a file should be copied to some other destination on the remote machine, +use :code:`--dest`:: + + copy --dest some-other-name some-file + +Glob patterns can be specified to copy multiple files, with :code:`--glob`:: + + copy --glob images/*.png + +Files can be excluded when copying with :code:`--exclude`:: + + copy --glob --exclude *.jpg --exclude *.bmp images/* + +Files whose remote name matches the exclude pattern will not be copied. +For more details, see :ref:`ssh_copy_command`. ''') opt('+env', '', option_type='env', add_to_default=False, long_text=''' diff --git a/kitty/conf/types.py b/kitty/conf/types.py index 2bd4aeaf3..defe2af53 100644 --- a/kitty/conf/types.py +++ b/kitty/conf/types.py @@ -52,6 +52,7 @@ def ref_map() -> Dict[str, str]: 'watchers': f'{website_url("launch")}#watchers', 'sessions': f'{website_url("overview")}#startup-sessions', 'functional': f'{website_url("keyboard-protocol")}#functional-key-definitions', + 'ssh_copy_command': f'{website_url("kittens/ssh")}#ssh-copy-command', 'shell_integration': website_url("shell-integration"), 'github_discussions': 'https://github.com/kovidgoyal/kitty/discussions', }