[ANN] Net::SFTP 0.5.0

[Jamis Buck]

Net::SFTP is a pure-Ruby implementation of the SFTP client protocol,
versions 1 through 5. It requires Net::SSH 0.6.0.

project page: http://rubyforge.org/projects/net-ssh

Documentation is severely lacking in this release, and I apologize for
that. But I'm wanting to try something new for the user manual, and I
figured I'd rather release something now without the user manual, than
wait a few more weeks (or more) while the user manual solidifies.

(Incidentally, you can join the net-ssh-users mailing list if you want
help using either Net::SFTP or Net::SSH:
http://rubyforge.org/mailman/listinfo/net-ssh-users)

So, in lieu of real documentation, here are a few usage examples:

1. Transfering a remote file to the local filesystem:

require 'net/sftp'

Net::SFTP.start( 'remote.host' ) do |sftp|
handle = sftp.open( "/path/to/remote/file.txt" )
contents = sftp.read( handle )
sftp.close_handle( handle )

File.open( "/path/to/local/file.txt ) { |f| f.write contents }
end

(Yes, I know the "open" should mimic the transactional interface
provided by, for instance, File, but it can't right now. A later release
will provide a #open_handle convenience method for doing that.)

2. Transfering a local file to the remote file system:

require 'net/sftp'

Net::SFTP.start( 'remote.host' ) do |sftp|
contents = File.read( "/path/to/local/file.txt" )

handle = sftp.open( "/path/to/remote/file.txt",
IO::WRITE | IO::CREAT )
contents = sftp.write( handle, contents )
sftp.close_handle( handle )
end

3. Getting a list of the contents of a remote directory:

require 'net/sftp'

Net::SFTP.start( 'remote.host' ) do |sftp|
handle = sftp.opendir( "/path/to/remote/dir" )
sftp.readdir( handle ).each { |item| puts item.filename }
sftp.close_handle( handle )
end

4. Querying (for instance) the size of a remote file:

require 'net/sftp'

Net::SFTP.start( 'remote.host' ) do |sftp|
size = sftp.stat( "/path/to/remote/file.txt" ).size
end

5. Creating and remove a remote directory:

require 'net/sftp'

Net::SFTP.start( 'remote.host' ) do |sftp|
sftp.mkdir( "/path/to/remote/directory", ermissions => 0660 )
sftp.rmdir( "/path/to/remote/directory )
end

6. Changing the user and/or owner of a file:

require 'net/sftp'

Net::SFTP.start( 'remote.host' ) do |sftp|
sftp.setstat( "/path/to/file.txt",
:uid => 1001,
:gid => 100 )
end

(Yah, that's kind of nasty, how it uses the id numbers directly, but
that's the way the SFTP protocol does it, prior to version 4, and all
SFTP servers that I know of only support up to version 3.)

Anyway, there are more examples in the 'examples' subdirectory of the
distribution. Enjoy!

- Jamis