From 05aab3e0124467f71038975ec3f3eb463c078d59 Mon Sep 17 00:00:00 2001 From: Tim Cross Date: Wed, 15 Jan 2020 10:10:39 +1100 Subject: [PATCH] Update README as prep for release 5.0.0 --- README.md | 292 ++++++++++++++++++++++++++++------------------------- README.org | 8 ++ 2 files changed, 160 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index f5713c3..663ed21 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,79 @@ # Table of Contents -1. [SSH2 SFTP Client](#org4816652) -2. [Installation](#org62d8b0f) -3. [Basic Usage](#org08888c9) -4. [Version 5.x](#orgd32ef38) - 1. [Breaking Changes in Version 5.x](#org2197c97) - 1. [Error Event Handling](#orgb1e5f0a) - 2. [Technical Details](#orge3148a6) - 2. [New Methods](#orgd276469) -5. [Documentation](#orge85324c) - 1. [Specifying Paths](#orgeb3ef2e) - 2. [Methods](#org6c7f22f) - 1. [new SftpClient(name) ===> SFTP client object](#org9e34ba8) - 2. [connect(config) ===> SFTPstream](#org7747b1a) - 3. [list(path, pattern) ==> Array[object]](#org4d70db3) - 4. [exists(path) ==> boolean](#org921e7bd) - 5. [stat(path) ==> object](#org8f40c2c) - 6. [get(path, dst, options) ==> String|Stream|Buffer](#org1088960) - 7. [fastGet(remotePath, localPath, options) ===> string](#org4aa1e36) - 8. [put(src, remotePath, options) ==> string](#org9a04d36) - 9. [fastPut(localPath, remotePath, options) ==> string](#org846df6f) - 10. [append(input, remotePath, options) ==> string](#org317696b) - 11. [mkdir(path, recursive) ==> string](#org525b611) - 12. [rmdir(path, recursive) ==> string](#org1f377f0) - 13. [delete(path) ==> string](#org661927c) - 14. [rename(fromPath, toPath) ==> string](#orgbb521d8) - 15. [chmod(path, mode) ==> string](#orga8bc61c) - 16. [realPath(path) ===> string](#orga5e14d7) - 17. [cwd() ==> string](#orgfa921c6) - 18. [uploadDir(srcDir, dstDir) ==> string](#org45c0f92) - 19. [downloadDir(srcDir, dstDir) ==> string](#orgaa563a2) - 20. [end() ==> boolean](#org3170762) - 21. [Add and Remove Listeners](#orga012803) -6. [FAQ](#org7e52a35) - 1. [Remote server drops connections with only an end event](#org57f88cd) - 2. [How can you pass writable stream as dst for get method?](#org88c1d4e) - 3. [How can I upload files without having to specify a password?](#org62015bb) - 4. [How can I connect through a Socks Proxy](#org3779300) - 5. [Timeout while waiting for handshake or handshake errors](#org3a6d3aa) -7. [Change Log](#orgaedfbfa) - 1. [v5.0.0 (Prod version)](#org761d890) - 2. [v4.3.1](#org8c97f38) - 3. [v4.3.0](#orgcd53aa3) - 4. [v4.2.4](#org9b98a53) - 5. [v4.2.3](#org16eb76b) - 6. [v4.2.2](#orgd1b511f) - 7. [v4.2.1](#org43b456f) - 8. [v4.2.0](#org2494ccf) - 9. [v4.1.0](#orgb72d730) - 10. [v4.0.4](#org814eed4) - 11. [v4.0.3](#org1352536) - 12. [v4.0.2](#org45bf89e) - 13. [v4.0.0](#org47ad9ce) - 14. [v2.5.2](#orgf8c7133) - 15. [v2.5.1](#org8d62462) - 16. [v2.5.0](#org8366b77) - 17. [v2.4.3](#org4c689d1) - 18. [v2.4.2](#org84bef78) - 19. [v2.4.1](#org2f95ec6) - 20. [v2.4.0](#org07ff009) - 21. [v2.3.0](#orgc930308) - 22. [v3.0.0 – deprecate this version](#org1af3a53) - 23. [v2.1.1](#orgc276e1e) - 24. [v2.0.1](#org22bbbbc) - 25. [v1.1.0](#org29dc31d) - 26. [v1.0.5:](#org4bdc0d0) -8. [Troubleshooting](#org6c39c24) -9. [Logging Issues](#org711a797) -10. [Pull Requests](#org1bc1bb7) -11. [Contributors](#orgcaa505b) - - - +1. [SSH2 SFTP Client](#org4291a1b) +2. [Installation](#orgdefe19d) +3. [Basic Usage](#org34ee016) +4. [Version 5.x](#orgf2f667e) + 1. [Breaking Changes in Version 5.x](#org7cf558a) + 1. [Error Event Handling](#orga6ba755) + 2. [Technical Details](#orgc369994) + 2. [New Methods](#org28ab508) +5. [Documentation](#org5d6a94c) + 1. [Specifying Paths](#org4f52805) + 2. [Methods](#orgf0cc376) + 1. [new SftpClient(name) ===> SFTP client object](#org3dac033) + 2. [connect(config) ===> SFTPstream](#orgaeeb2f8) + 3. [list(path, pattern) ==> Array[object]](#orge8dad3b) + 4. [exists(path) ==> boolean](#org070ed87) + 5. [stat(path) ==> object](#org16daf75) + 6. [get(path, dst, options) ==> String|Stream|Buffer](#org4efeaf8) + 7. [fastGet(remotePath, localPath, options) ===> string](#orgb494c68) + 8. [put(src, remotePath, options) ==> string](#org31d0a6e) + 9. [fastPut(localPath, remotePath, options) ==> string](#org95dc0d1) + 10. [append(input, remotePath, options) ==> string](#org99ac1a5) + 11. [mkdir(path, recursive) ==> string](#orgd23cc81) + 12. [rmdir(path, recursive) ==> string](#org1c1bd8a) + 13. [delete(path) ==> string](#orgffccdb4) + 14. [rename(fromPath, toPath) ==> string](#org9362bd0) + 15. [chmod(path, mode) ==> string](#org403745f) + 16. [realPath(path) ===> string](#org8fe786f) + 17. [cwd() ==> string](#org17456f3) + 18. [uploadDir(srcDir, dstDir) ==> string](#orgb095c84) + 19. [downloadDir(srcDir, dstDir) ==> string](#org1913fd1) + 20. [end() ==> boolean](#org0350bf7) + 21. [Add and Remove Listeners](#org6f7dd30) +6. [FAQ](#org61f1f47) + 1. [Remote server drops connections with only an end event](#orge352f47) + 2. [How can you pass writable stream as dst for get method?](#org3ddb1ab) + 3. [How can I upload files without having to specify a password?](#orgb79d177) + 4. [How can I connect through a Socks Proxy](#orgd9a353d) + 5. [Timeout while waiting for handshake or handshake errors](#org775c973) +7. [Examples](#org1287c2a) +8. [Change Log](#org834ce76) + 1. [v5.0.0 (Prod version)](#org4edde76) + 2. [v4.3.1](#org5f3379d) + 3. [v4.3.0](#orge312e05) + 4. [v4.2.4](#orgc8bb9da) + 5. [v4.2.3](#orgf93cb12) + 6. [v4.2.2](#org816f83b) + 7. [v4.2.1](#org0078e28) + 8. [v4.2.0](#orgd328129) + 9. [v4.1.0](#org51b15c5) + 10. [v4.0.4](#org5b6acc6) + 11. [v4.0.3](#orgf378a00) + 12. [v4.0.2](#orgff0223d) + 13. [v4.0.0](#orgf275fe0) + 14. [v2.5.2](#orgd6ce7b4) + 15. [v2.5.1](#orgaafbb99) + 16. [v2.5.0](#org90bab19) + 17. [v2.4.3](#orgb2767f3) + 18. [v2.4.2](#org4b785b8) + 19. [v2.4.1](#org7d27fbd) + 20. [v2.4.0](#org85e4b9f) + 21. [v2.3.0](#orgd95c97a) + 22. [v3.0.0 – deprecate this version](#orgdadb7c8) + 23. [v2.1.1](#org1e455cf) + 24. [v2.0.1](#org823d63b) + 25. [v1.1.0](#orge9495d0) + 26. [v1.0.5:](#org8c33c2e) +9. [Troubleshooting](#org099ac4e) +10. [Logging Issues](#orge56ff26) +11. [Pull Requests](#org067ccb3) +12. [Contributors](#org9e8f104) + + + # SSH2 SFTP Client @@ -89,14 +90,14 @@ Code has been tested against Node versions 10.17.0 and 12.14.0 Node versions < 10.x are not supported. - + # Installation npm install ssh2-sftp-client - + # Basic Usage @@ -117,12 +118,12 @@ Node versions < 10.x are not supported. }); - + # Version 5.x - + ## Breaking Changes in Version 5.x @@ -151,7 +152,7 @@ Node versions < 10.x are not supported. occur during a call to end the connection. - + ### Error Event Handling @@ -247,7 +248,7 @@ want to end, then you can just ignore the error, perform any necessary cleanup work and exit successfully. - + ### Technical Details @@ -267,7 +268,7 @@ further attempts to use it and finally, ensure the `this.errorHandler` flag is reset to false in preparation for the next error. - + ## New Methods @@ -283,7 +284,7 @@ reset to false in preparation for the next error. any local files in the directories. - + # Documentation @@ -294,7 +295,7 @@ All the methods will return a Promise, except for `on()` and `removeListener()`, which are typically only used in special use cases. - + ## Specifying Paths @@ -332,12 +333,12 @@ This will copy the local file `test.txt` to the remote file `test-copy.txt` in the directory `/remote/dir`. - + ## Methods - + ### new SftpClient(name) ===> SFTP client object @@ -376,7 +377,7 @@ client has thrown the error. }); - + ### connect(config) ===> SFTPstream @@ -446,7 +447,7 @@ available [here](https://github.com/mscdex/ssh2#user-content-client-methods) }); - + ### list(path, pattern) ==> Array[object] @@ -519,7 +520,7 @@ directory. anchor matches to the beginning/end of the string etc. - + ### exists(path) ==> boolean @@ -554,7 +555,7 @@ if it exists or false if it does not. }); - + ### stat(path) ==> object @@ -601,7 +602,7 @@ Returns the attributes associated with the object pointed to by `path`. }); - + ### get(path, dst, options) ==> String|Stream|Buffer @@ -662,7 +663,7 @@ better off using the `fastGet()` method. decompress a gzip file 'on the fly'. - + ### fastGet(remotePath, localPath, options) ===> string @@ -705,7 +706,7 @@ throughput. This is the simplest method if you just want to download a file. }); - + ### put(src, remotePath, options) ==> string @@ -758,7 +759,7 @@ stream are piped to the `remotePath` on the server. - **Tip:** If the src argument is a path string, consider just using `fastPut()`. - + ### fastPut(localPath, remotePath, options) ==> string @@ -801,7 +802,7 @@ Uploads the data in file at `localPath` to a new file on remote server at }); - + ### append(input, remotePath, options) ==> string @@ -846,7 +847,7 @@ in to the file. }); - + ### mkdir(path, recursive) ==> string @@ -875,7 +876,7 @@ defaults to false. }); - + ### rmdir(path, recursive) ==> string @@ -905,7 +906,7 @@ action will fail. }); - + ### delete(path) ==> string @@ -930,7 +931,7 @@ Delete a file on the remote server. }); - + ### rename(fromPath, toPath) ==> string @@ -955,7 +956,7 @@ necessary permissions to modify the remote file. }); - + ### chmod(path, mode) ==> string @@ -983,7 +984,7 @@ directory. }); - + ### realPath(path) ===> string @@ -995,14 +996,14 @@ path is not valid. does not expand '~'. - + ### cwd() ==> string Returns what the server believes is the current remote working directory. - + ### uploadDir(srcDir, dstDir) ==> string @@ -1068,7 +1069,7 @@ using the `on()` method. }); - + ### downloadDir(srcDir, dstDir) ==> string @@ -1134,7 +1135,7 @@ the `on()` method. }); - + ### end() ==> boolean @@ -1157,7 +1158,7 @@ resources. This function also removes all listeners associated with the client. }); - + ### Add and Remove Listeners @@ -1183,12 +1184,12 @@ them have any meaning in the context of SFTP. These are the `end()` method automatically removes all listeners from the client object. - + # FAQ - + ## Remote server drops connections with only an end event @@ -1218,7 +1219,7 @@ that the 1st connection has completed authentication before the 11th connection is attempted. - + ## How can you pass writable stream as dst for get method? @@ -1282,7 +1283,7 @@ bring them across before saving to local file system. }); - + ## How can I upload files without having to specify a password? @@ -1317,7 +1318,7 @@ configuration. } - + ## How can I connect through a Socks Proxy @@ -1351,7 +1352,7 @@ This solution was provided by @jmorino. // client is connected - + ## Timeout while waiting for handshake or handshake errors @@ -1366,12 +1367,23 @@ documentation for details. Getting these parameters correct usually resolves the issue. - + + +# Examples + +I have started collecting example scripts in the example directory of the +repository. These are mainly scripts I have put together in order to investigate +issues or provide samples for users. They are not robust, lack adequate error +handling and may contain errors. However, I think they are still useful for +helping developers see how the module and API can be used. + + + # Change Log - + ## v5.0.0 (Prod version) @@ -1390,7 +1402,7 @@ issue. - Any error events fired during an `end()` call are now ignored. - + ## v4.3.1 @@ -1400,7 +1412,7 @@ issue. causing uncaughtException erros and causing the process to exit. - + ## v4.3.0 @@ -1410,7 +1422,7 @@ issue. `error.message`. - + ## v4.2.4 @@ -1419,7 +1431,7 @@ issue. - Clarify documentation on get() method - + ## v4.2.3 @@ -1428,7 +1440,7 @@ issue. - Clean up mkdir example - + ## v4.2.2 @@ -1436,7 +1448,7 @@ issue. - Added additional examples in the `example` directory - + ## v4.2.1 @@ -1450,7 +1462,7 @@ issue. debugging - + ## v4.2.0 @@ -1461,7 +1473,7 @@ issue. - Added additional examples in `example` directory - + ## v4.1.0 @@ -1478,7 +1490,7 @@ issue. - Add `cwd()` method - + ## v4.0.4 @@ -1486,7 +1498,7 @@ issue. - Fix return value from `get()` - + ## v4.0.3 @@ -1494,14 +1506,14 @@ issue. - Modify exists() to always return 'd' if path is '.' - + ## v4.0.2 - Fix some minor packaging issues - + ## v4.0.0 @@ -1519,7 +1531,7 @@ issue. - Added the `removeListener()` method to compliment the existing `on()` method. - + ## v2.5.2 @@ -1527,21 +1539,21 @@ issue. - Fix error in package.json pointing to wrong repository - + ## v2.5.1 - Apply 4 pull requests to address minor issues prior to transfer - + ## v2.5.0 - ??? - + ## v2.4.3 @@ -1549,7 +1561,7 @@ issue. - fix connect promise if connection ends - + ## v2.4.2 @@ -1557,7 +1569,7 @@ issue. - fix windows path - + ## v2.4.1 @@ -1565,7 +1577,7 @@ issue. - bug fix - + ## v2.4.0 @@ -1578,7 +1590,7 @@ issue. - Added new 'exists' method and re-factored mkdir/rmdir - + ## v2.3.0 @@ -1587,7 +1599,7 @@ issue. - fix: `mkdir` file exists decision logic - + ## v3.0.0 – deprecate this version @@ -1595,7 +1607,7 @@ issue. - fix: get readable not emitting data events in node 10.0.0 - + ## v2.1.1 @@ -1603,7 +1615,7 @@ issue. - add: `get` or `put` method add extra options [pr#52](https://github.com/jyu213/ssh2-sftp-client/pull/52) - + ## v2.0.1 @@ -1613,14 +1625,14 @@ issue. - fix: return Error object on promise rejection [pr#20](https://github.com/jyu213/ssh2-sftp-client/pull/20) - + ## v1.1.0 - fix: add encoding control support for binary stream - + ## v1.0.5: @@ -1628,7 +1640,7 @@ issue. - change: remove `this.client.sftp` to `connect` function - + # Troubleshooting @@ -1669,7 +1681,7 @@ trying to determine if the issue is with the underlying `ssh2` and `ssh2-streams` modules. - + # Logging Issues @@ -1694,7 +1706,7 @@ Perhaps the best assistance is a minimal reproducible example of the issue. Once the issue can be readily reproduced, it can usually be fixed very quickly. - + # Pull Requests @@ -1714,7 +1726,7 @@ your pull request what level of change it represents i.e. bug. - + # Contributors diff --git a/README.org b/README.org index 91e47cb..2591890 100644 --- a/README.org +++ b/README.org @@ -1251,6 +1251,14 @@ host key used to establish the initial secure connection. See the SSH2 documentation for details. Getting these parameters correct usually resolves the issue. +* Examples + +I have started collecting example scripts in the example directory of the +repository. These are mainly scripts I have put together in order to investigate +issues or provide samples for users. They are not robust, lack adequate error +handling and may contain errors. However, I think they are still useful for +helping developers see how the module and API can be used. + * Change Log ** v5.0.0 (Prod version) - Added two new methods ~uploadDir()~ and ~downloadDir()~