branch: externals/ssh-deploy
commit 5d70d89cddae17e4e412c9246871c3cbc860e3c6
Author: Christian Johansson <christ...@cvj.se>
Commit: Christian Johansson <christ...@cvj.se>
Improved documentation
---
README.md | 53 +++++++++++++++++++++++++++++------------------------
ssh-deploy.el | 53 +++++++++++++++++++++++++++++++++++++++++++++++------
2 files changed, 76 insertions(+), 30 deletions(-)
diff --git a/README.md b/README.md
index 40f7322..7429025 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,11 @@ The `ssh-deploy` plug-in for Emacs makes it possible to
effortlessly deploy loca
* Automatic and manual detection of remote changes of files using local
revisions
* Launch remote `eshell` terminals in base or relative directory
* Launch remote `dired` browsing in base or relative directory
-* Launch difference sessions for files and directories using `ediff-mode`
-* Supports asynchronous operations if `async.el` is installed. (You need to
setup an automatic authorization for this, i.e. `~/.netrc` or key-based
password-less authorization)
-* Supports renaming and deletion of files and directories on local host and
mirrored on remote
+* Launch difference sessions for files using `ediff`
+* Launch difference sessions for directories using a custom implementation of
recursive directory differences over TRAMP based on `ediff`
+* Rename files and directories on local host and have it mirrored on the remote
+* Delete files and directories on local host and have it mirrored on the remote
+* All operations support asynchronous mode if `async.el` is installed. (You
need to setup an automatic authorization for this, i.e. `~/.netrc` and/or
key-based password-less authorization)
The idea for this plug-in was to mimic the behavior of **PhpStorm** deployment
functionality.
@@ -32,10 +34,10 @@ Here is a list of other variables you can set globally or
per directory:
## Deployment configuration examples
-* Download ssh-deploy and place it at `~/.emacs.d/ssh-deploy/` or install via
`package.el` (`M-x list-packages`) from the `MELPA` repository.
+* Download ssh-deploy and place it at `~/.emacs.d/ssh-deploy/` or install via
`package.el` (`M-x list-packages` or `M-x package-install` + `ssh-deploy`) from
the `MELPA` repository.
* So if you want to deploy `/Users/username/Web/MySite/` to create this
`DirectoryVariables` file in your project root at
`/Users/username/Web/MySite/.dir-locals.el`.
-You really need to research how you connect via different protocols using
TRAMP on your operating system, I think Windows users should use `plink` for
most protocols.
+You really need to do a bit of research about how to connect via different
protocols using TRAMP on your operating system, I think Windows users should
use `plink` for most protocols. Linux should work out of the box and macOS
requires a bit of tweaking to get FTP support.
### SSH/SFTP
@@ -47,8 +49,6 @@ You really need to research how you connect via different
protocols using TRAMP
)))
```
-NOTE: I'm not sure how to get pure `sftp` working on macOS, but this should
work on other *NIX systems:
-
``` emacs-lisp
((nil . (
(ssh-deploy-root-local . "/Users/username/Web/MySite/")
@@ -68,7 +68,7 @@ You can pipe remote connections as well like this:
)))
```
-If you have a password-less sudo on your remote host you should be to enable
`async`.
+If you have a password-less sudo on your remote host you should be to do this
asynchronously.
### FTP
@@ -80,13 +80,13 @@ If you have a password-less sudo on your remote host you
should be to enable `as
)))
```
-## Interaction-free SSH setup
+## Interaction-free SSH setup using password-less public-key authorization
-For automatic **SSH** connections you need to setup a password-less public-key
authorization.
+For automatic **SSH** connections you need to setup a password-less public-key
authorization. You need to research how to setup this on your operating system.
-## More complex SSH connections
+## Changing SSH port or public-key identify-file per host
-If you have a SSH connection that is using a different identity-file than the
default, or if it is using a different port than the default you just need to
edit your local SSH-config `~/ssh/config` to make it work using this plugin,
like this:
+If you have a SSH connection that is using a different identity-file than the
default, or if it is using a different port than the default you just need to
edit your local SSH-config `~/.ssh/config` to make it work using this plug-in,
like this:
``` bash
## My special connection (replace remote-host, remote-port and identity-file
with your values)
@@ -108,9 +108,13 @@ machine myserver3.com login myuser3 port sftp password
mypassword3
Set your user and group as owner and file permissions to `600`. Emacs should
now be able to automatically connect to this server via FTP without any user
interaction.
-## Emacs init script
+## Interaction-free SSH setup using public-key password-based authorization
+
+By combining a `~/.netrc` setup and a `public-key` setup you should be able to
have a interaction-free public-key password-based authorization that can be
used asynchronously.
+
+## Emacs configuration example
-* And add this to your *emacs-init-script*:
+* And add this to your *emacs-init-script*: (1)
``` elisp
;; ssh-deploy - prefix = C-c C-z, f = forced upload, u = upload, d = download,
x = diff, t = terminal, b = browse
@@ -134,6 +138,7 @@ Set your user and group as owner and file permissions to
`600`. Emacs should now
``` elisp
(use-package ssh-deploy
+ :ensure t
:demand
:bind (("C-c C-z" . hydra-ssh-deploy/body))
:hook ((after-save . (lambda() (if (and (boundp
'ssh-deploy-on-explicit-save) ssh-deploy-on-explicit-save)
(ssh-deploy-upload-handler)) ))
@@ -163,26 +168,26 @@ Set your user and group as owner and file permissions to
`600`. Emacs should now
("B" ssh-deploy-browse-remote-handler)))
```
-You can remove the `(add-to-list)` and `(require)` lines if you installed via
`MELPA` repository.
+(1) You can remove the `(add-to-list)` and `(require)` lines if you installed
via `MELPA` repository.
-* Restart Emacs
+* Restart Emacs or re-evaluate your *emacs-init-script*
-## Usage
+## Example usage
* Now when you save a file somewhere under the directory
`/Users/username/Web/MySite/`, the script will launch and deploy the file with
the remote server.
-* If you press `C-c C-z x` and the current buffer is a file, you will launch a
`ediff` session showing differences between local file and remote file via
`tramp`, or if current buffer is a directory it will open a buffer showing
directory differences
+* If you press `C-c C-z x` and the current buffer is a file, you will launch a
`ediff` session showing differences between local file and remote file via
TRAMP, or if current buffer is a directory it will open a buffer showing
directory differences
* If you press `C-c C-z f` you will **force** upload local file or directory
to remote host even if they have external changes.
* If you press `C-c C-z u` you will upload local file or directory to remote
host.
* If you press `C-c C-z d` you will download the current file or directory
from remote host and then reload current buffer.
* If you press `C-c C-z D` you will delete the current file or directory after
a confirmation on local and remote host.
* If you press `C-c C-z t` you will open a terminal with remote host in base
directory via `eshell`.
* If you press `C-c C-z T` you will open a terminal with remote host in
current directory via `eshell`.
-* If you press `C-c C-z b` you will browse base directory on remote host in
`dired-mode`.
-* If you press `C-c C-z B` you will browse current directory on remote host in
`dired-mode`.
+* If you press `C-c C-z b` you will browse base directory on remote host in
`dired`.
+* If you press `C-c C-z B` you will browse current directory on remote host in
`dired`.
* If you press `C-c C-z R` you will rename current file or directory.
* If you press `C-c C-z e` you will check for remote changes to the current
file.
-The local path and local root is evaluated based on their **truename** so if
you use different symbolic local paths it shouldn't affect the deployment
procedure.
+The local path and local root is evaluated based on their `truename` so if you
use different symbolic local paths it shouldn't affect the deployment procedure.
The above configuration example uses the Emacs plug-in `use-package` which I
highly recommend.
@@ -197,9 +202,9 @@ macOS 10.13 removed the Darwin port of BSD `ftp` which is
needed for `ange-ftp`,
5. Type `mv ./src/ftp /usr/local/bin/ftp`
## Read more
-* <https://www.emacswiki.org/emacs/DirectoryVariables>
* <http://www.gnu.org/software/tramp/>
-* <https://github.com/jwiegley/use-package>
-* <https://www.emacswiki.org/emacs/EdiffMode>
* <http://melpa.org/>
+* <https://www.emacswiki.org/emacs/DirectoryVariables>
+* <https://www.emacswiki.org/emacs/EdiffMode>
* <https://github.com/jwiegley/emacs-async>
+* <https://github.com/jwiegley/use-package>
diff --git a/ssh-deploy.el b/ssh-deploy.el
index e04e892..204cf34 100644
--- a/ssh-deploy.el
+++ b/ssh-deploy.el
@@ -46,7 +46,7 @@
;; machine myserver2.com login myuser2 port ssh password mypassword2
;; machine myserver3.com login myuser3 port sftp password mypassword3
;;
-;; Set permissions to this file to 700 with you as the owner.
+;; Set permissions to this file to 600 with your user as the owner.
;;
;; - To setup a upload hook on save do this:
;; (add-hook 'after-save-hook (lambda() (if (and (boundp
'ssh-deploy-on-explicit-save) ssh-deploy-on-explicit-save)
(ssh-deploy-upload-handler)) ))
@@ -67,20 +67,61 @@
;; (global-set-key (kbd "C-c C-z b") (lambda()
(interactive)(ssh-deploy-browse-remote-base-handler) ))
;; (global-set-key (kbd "C-c C-z B") (lambda()
(interactive)(ssh-deploy-browse-remote-handler) ))
;;
-;; Here is an example for SSH/SFTP deployment,
/Users/Chris/Web/Site1/.dir-locals.el:
+;; - To install and set-up using use-package and hydra do this:
+;; (use-package ssh-deploy
+;; :ensure t
+;; :demand
+;; :bind (("C-c C-z" . hydra-ssh-deploy/body))
+;; :hook ((after-save . (lambda() (if (and (boundp
'ssh-deploy-on-explicit-save) ssh-deploy-on-explicit-save)
(ssh-deploy-upload-handler)) ))
+;; (find-file . (lambda() (if (and (boundp
'ssh-deploy-automatically-detect-remote-changes)
ssh-deploy-automatically-detect-remote-changes)
(ssh-deploy-remote-changes-handler)) )))
+;; :config
+;; (defhydra hydra-ssh-deploy (:color red :hint nil)
+;; "
+;; _u_: Upload _f_: Force Upload
+;; _d_: Download
+;; _D_: Delete
+;; _x_: Difference
+;; _t_: Eshell Base Terminal _T_: Eshell Relative Terminal
+;; _e_: Detect Remote Changes
+;; _R_: Rename
+;; _b_: Browse Base _B_: Browse Relative
+;; "
+;; ("f" ssh-deploy-upload-handler-forced)
+;; ("u" ssh-deploy-upload-handler)
+;; ("d" ssh-deploy-download-handler)
+;; ("D" ssh-deploy-delete-handler)
+;; ("x" ssh-deploy-diff-handler)
+;; ("t" ssh-deploy-remote-terminal-eshell-base-handler)
+;; ("T" ssh-deploy-remote-terminal-eshell-handler)
+;; ("e" ssh-deploy-remote-changes-handler)
+;; ("R" ssh-deploy-rename-handler)
+;; ("b" ssh-deploy-browse-remote-base-handler)
+;; ("B" ssh-deploy-browse-remote-handler)))
+;;
+;;
+;; Here is an example for SSH deployment,
/Users/Chris/Web/Site1/.dir-locals.el:
;; ((nil . (
;; (ssh-deploy-root-local . "/Users/Chris/Web/Site1/")
;; (ssh-deploy-root-remote . "/ssh:myu...@myserver.com:/var/www/site1/")
-;; (ssh-deploy-on-explicity-save . t)
+;; (ssh-deploy-on-explicit-save . t)
+;; (ssh-deploy-async . t)
;; )))
;;
-;; Here is an example for FTP deployment,
/Users/Chris/Web/Site2/.dir-locals.el:
+;; Here is an example for SFTP deployment,
/Users/Chris/Web/Site2/.dir-locals.el:
;; ((nil . (
;; (ssh-deploy-root-local . "/Users/Chris/Web/Site2/")
-;; (ssh-deploy-root-remote . "/ftp:myu...@myserver.com:/var/www/site2/")
+;; (ssh-deploy-root-remote . "/sftp:myu...@myserver.com:/var/www/site2/")
;; (ssh-deploy-on-explicit-save . nil)
+;; (ssh-deploy-async . nil)
+;; )))
+;;
+;; Here is an example for FTP deployment,
/Users/Chris/Web/Site3/.dir-locals.el:
+;; ((nil . (
+;; (ssh-deploy-root-local . "/Users/Chris/Web/Site3/")
+;; (ssh-deploy-root-remote . "/ftp:myu...@myserver.com:/var/www/site3/")
;; )))
;;
+;;
;; Now when you are in a directory which is configured for deployment.
;;
;; Here is a list of other variables you can set globally or per directory:
@@ -94,7 +135,7 @@
;; * ssh-deploy-exclude-list - A list defining what paths to exclude from
deployment *(list)*
;; * ssh-deploy-async - Enables asynchronous transfers (you need to have
`async.el` installed as well) *(boolean)*
;;
-;; Please see README.md from the same repository for documentation.
+;; Please see README.md from the same repository for extended documentation.
;;; Code:
