Merge branch 'release/0.4.0'

Author: hugoduncan

.gitignore

@@ -5,3 +5,5 @@ lib
 classes
 autodoc/**
 doc/**
+.lein-deps-sum
+.lein-failures

README.md

@@ -1,62 +1,87 @@
 # clj-ssh
 
-SSH in clojure.  Uses jsch.  Provides a ssh function that tries to look similar
-to clojure.contrib.shell/sh.
+SSH in clojure.  Uses jsch.
 
 ## Usage
 
-The top level namespace is `clj-ssh.ssh`
+### REPL
 
-    (use 'clj-ssh.ssh)
+The `clj-ssh.cli` namespace provides some functions for ease of use at the REPL.
 
-There is a simple `ssh` function, which by default, will try and use a id_rsa
-key in your $HOME/.ssh directory.
-
-    (ssh "hostname" "ls")
-
-Strict host key checking can be turned off.
+```clj
+(use 'clj-ssh.cli)
+```
 
-    (default-session-options {:strict-host-key-checking :no})
+Use `ssh` to execute a command, say `ls`, on a remote host "my-host",
 
-By default, your current username and id_rsa key are used.  If your key has a
-passphrase, and you are on OSX, then you should be asked for access to your
-keychain.  If you are on any other OS, you will need to explicitly add your key
-to the clj-ssh's ssh-agent with the appropriate add-identity call.
+```clj
+(ssh "my-host" "ls")
+  => {:exit 0 :out "file1\nfile2\n" :err "")
+```
 
-More advance usage is possible.
+By default this will use the system ssh-agent to obtain your ssh keys, and it
+uses your current username, but this can be specified:
 
-    (with-ssh-agent []
-      (add-identity "/user/name/.ssh/id_dsa")
-      (let [session (session "localhost" :strict-host-key-checking :no)]
-        (with-connection session
-          (let [result (ssh session :in "echo hello" :result-map true)]
-            (println (result :out)))
-          (let [result (ssh session "/bin/bash" "-c" "ls" "/")]
-            (println (second result))))))
+```clj
+(ssh "my-host" "ls" :username "remote-user")
+  => {:exit 0 :out "file1\nfile2\n" :err "")
+```
 
-SFTP is supported, both with a simple interface,
+Strict host key checking can be turned off:
 
-     (sftp "hostname" :put "/from/this/path" "to/this/path")
+```clj
+(default-session-options {:strict-host-key-checking :no})
+```
 
-as well as more advanced usage.
+SFTP is also supported. For example, to copy a local file to a remote host
+"my-host":
 
-    (with-ssh-agent []
-      (let [session (session "localhost" :strict-host-key-checking :no)]
-        (with-connection session
-          (let [channel (ssh-sftp session)]
-            (with-connection channel
-              (sftp channel :cd "/remote/path")
-              (sftp channel :put "/some/file" "filename"))))))
+```clj
+(sftp "my-host" :put "/from/this/path" "to/this/path")
+```
 
 Note that any sftp commands that change the state of the sftp session (such as
 cd) do not work with the simplified interface, as a new session is created each
 time.
 
+If your key has a passphrase, you will need to explicitly add your key either to
+the system's ssh-agent, or to clj-ssh's ssh-agent with the appropriate
+`add-identity` call.
+
+### Non REPL
+
+The `clj-ssh.ssh` namespace should be using SSH from functional code.
+
+```clj
+(let [agent (ssh-agent {:use-system-ssh-agent false})]
+  (add-identity agent "/user/name/.ssh/id_rsa")
+  (let [session (session agent "localhost" {:strict-host-key-checking :no})]
+    (with-connection session
+      (let [result (ssh session {:in "echo hello"})]
+        (println (result :out)))
+      (let [result (ssh session {:cmd "ls"}]
+        (println (second result))))))
+```
+
+The above example shows using `:in` to pass commands to a shell, and using
+`:cmd` to exec a command without a shell. When using `:cmd` you can still pass
+a stream or a string to `:in` to be used as the process' standard input.
+
+```clj
+(let [agent (ssh-agent {})]
+  (let [session (session agent "localhost" {:strict-host-key-checking :no})]
+    (with-connection session
+      (let [channel (ssh-sftp session)]
+        (with-channel-connection channel
+          (sftp channel :cd "/remote/path")
+          (sftp channel :put "/some/file" "filename"))))))
+```
+
 SSH tunneling is also supported:
 
 ```clj
-    (with-ssh-agent []
-      (let [session (session "localhost" :strict-host-key-checking :no)]
+    (let [agent (ssh-agent {:use-system-ssh-agent false})]
+      (let [session (session agent "localhost" :strict-host-key-checking :no)]
         (with-connection session
           (with-local-port-forward [session 8080 80]
             (comment do something with port 8080 here)))))
@@ -69,11 +94,9 @@ SSH tunneling is also supported:
 
 ## FAQ
 
-Q: Why doesn't clj-ssh integrate with the OS's ssh agent?
-
-A: Java has no access to the Unix domain socket used by the system ssh-agent.
-
-Q: What does  "4: Failure @ com.jcraft.jsch.ChannelSftp.throwStatusError(ChannelSftp.java:2289)" during an sftp transfer signify?
+Q: What does
+"4: Failure @ com.jcraft.jsch.ChannelSftp.throwStatusError(ChannelSftp.java:2289)"
+during an sftp transfer signify?
 
 A: Probably a disk full, or permission error.
 
@@ -82,7 +105,7 @@ A: Probably a disk full, or permission error.
 Via [clojars](http://clojars.org) and
 [Leiningen](http://github.com/technomancy/leiningen).
 
-    :dependencies [clj-ssh "0.3.3"]
+    :dependencies [clj-ssh "0.4.0"]
 
 or your favourite maven repository aware tool.
 

ReleaseNotes.md

@@ -1,6 +1,16 @@
 # Release Notes
 
-Current release is 0.3.3
+Current release is 0.4.0
+
+## 0.4.0
+
+- Split out clj-ssh.cli
+
+  clj-ssh.ssh is designed for composability and programmatic use. It takes 
+  map arguments for options and is fully functional.
+
+  clj-ssh.cli is intended to simplify repl usage. It takes variadic
+  arguments for options and uses dynamic vars to provide defaults.
 
 ## 0.3.3
 

pom.xml

@@ -1,10 +1,20 @@
-(defproject clj-ssh "0.3.2-SNAPSHOT"
+(defproject clj-ssh "0.4.0"
   :description "Library for using SSH from clojure."
-  :dependencies [[org.clojure/clojure "1.2.0"]
+  :url "https://github.com/hugoduncan/clj-ssh"
+  :dependencies [[org.clojure/clojure "1.2.1"]
                  [org.clojure/tools.logging "0.1.2"]
-                 [slingshot "0.2.0"]
-                 [com.jcraft/jsch "0.1.44-1"]]
-  :dev-dependencies [[log4j/log4j "1.2.14"]]
+                 [jsch-agent-proxy "0.0.4"]
+                 [jsch-agent-proxy/jsch-agent-proxy-jna "0.0.4"
+                  :exclusions [com.jcraft/jsch-agent-proxy]]
+                 [slingshot "0.10.2"]
+                 [com.jcraft/jsch "0.1.48"]]
+  :dev-dependencies [[org.slf4j/slf4j-api "1.6.1"]
+                     [ch.qos.logback/logback-core "1.0.0"]
+                     [ch.qos.logback/logback-classic "1.0.0"]]
+  :profiles {:dev {:dependencies [[org.slf4j/slf4j-api "1.6.1"]
+                                  [ch.qos.logback/logback-core "1.0.0"]
+                                  [ch.qos.logback/logback-classic "1.0.0"]
+                                  [codox-md "0.1.0"]]}}
   :multi-deps {"slingshot-0.10.1" [[slingshot "0.10.1"]
                                    [org.clojure/clojure "1.2.1"]]
                "clojure-1.2.1" [[slingshot "0.10.1"]
@@ -14,5 +24,8 @@
                "clojure-1.4.0" [[slingshot "0.10.1"]
                                 [org.clojure/clojure "1.4.0-beta1"]]}
   :codox {:writer codox-md.writer/write-docs
-          :version "0.3"
-          :output-dir "doc/api/0.3"})
+          :version "0.4"
+          :output-dir "doc/api/0.4"
+          :exclude [clj-ssh.agent clj-ssh.reflect clj-ssh.keychain]}
+  :license {:name "Eclipse Public License"
+            :url "http://www.eclipse.org/legal/epl-v10.html"})