#+title:    :tools upload
#+subtitle: Map local directories to remotes via ssh/ftp
#+created:  February 20, 2017
#+since:    2.0.0

* Description :unfold:
Uses ~ssh-deploy~ to map a local folder to a remote one.

#+begin_quote
 󰝗 The ssh-deploy plug-in for Emacs makes it possible to effortlessly deploy
    local files and directories to remote hosts via Tramp (including but not
    limited to SSH, SFTP, FTP). It tries to provide functions that can be easily
    used by custom scripts.

    The idea for this plug-in was to mimic the behavior of PhpStorm deployment
    functionality. —[[https://github.com/emacsmirror/ssh-deploy][ssh-deploy README]]
#+end_quote

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
/This module has no flags./

** Packages
- [[doom-package:ssh-deploy]]

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

/This module has no external requirements./

* Usage
There are three ways to map a local directory to a remote one:

1. With a =.dir-locals.el= file at the root of your project/directory. E.g.
   #+begin_src emacs-lisp
   ((nil . ((ssh-deploy-root-local . "/local/path/to/project/")
            (ssh-deploy-root-remote . "/ssh:user@server:/remote/project/")
            (ssh-deploy-on-explicit-save . 1))))
   #+end_src

2. In file-local variables in the commented header at the top of a file:
   #+begin_src emacs-lisp
   ;; -*- ssh-deploy-root-remote: "/ssh:user@server:/remote/project/"; ssh-deploy-on-explicit-save: 1 -*-
   #+end_src

   Or in a commented block at the bottom of the file:
   #+begin_src emacs-lisp
   ;; -*-
   ;; Local Variables:
   ;; ssh-deploy-root-local: "/local/path/to/project/"
   ;; ssh-deploy-root-remote: "/ssh:user@server:/remote/project/"
   ;; ssh-deploy-on-explicit-save: 1
   ;; End:
   #+end_src

3. Manually, on a per-buffer basis, with the ~M-x +upload/register-remote~
   command. Use ~M-x +upload/unregister-all-remotes~ to undo all manual remotes.

#+begin_quote
 󰐃 ~ssh-deploy-root-local~ is optional, and will resort to ~doom-project-root~ if
    unspecified.
#+end_quote

* TODO Configuration
#+begin_quote
 󱌣 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

Check out [[https://github.com/cjohansson/emacs-ssh-deploy#deployment-configuration-examples][Deployment configuration examples]] for some ideas of what's possible.

* Troubleshooting
** ~root-local~ and ~root-remote~ must match
The final directory names much match:
#+begin_src emacs-lisp
((nil . ((ssh-deploy-root-local . "/local/path/to/example-project/")
         (ssh-deploy-root-remote . "/ssh:user@server:/remote/example-project/")
#+end_src

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote
