From d5c246b7619f780db3576a08c2d2fd0c1a17d421 Mon Sep 17 00:00:00 2001 From: Tim Cross Date: Thu, 16 Jan 2020 18:35:28 +1100 Subject: [PATCH] re-generate README.md --- README.md | 306 +++++++++++++++++++++++++++++------------------------- 1 file changed, 163 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index 663ed21..db00eaf 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,81 @@ # Table of Contents -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) - - - +1. [SSH2 SFTP Client](#org14abbd2) +2. [Installation](#org7c764b7) +3. [Basic Usage](#org8d031a6) +4. [Version 5.x](#org1a89ba3) + 1. [Breaking Changes in Version 5.x](#orgb276240) + 1. [Error Event Handling](#orge8889c7) + 2. [Technical Details](#orge87496f) + 2. [New Methods](#org9209cc8) + 3. [Version 5.0.1](#orgd216ae6) +5. [Documentation](#org086d499) + 1. [Specifying Paths](#orgb9264ce) + 2. [Methods](#orgdc6a566) + 1. [new SftpClient(name) ===> SFTP client object](#orgae36643) + 2. [connect(config) ===> SFTPstream](#orge4e0e8f) + 3. [list(path, pattern) ==> Array[object]](#org51930e3) + 4. [exists(path) ==> boolean](#org10c80a4) + 5. [stat(path) ==> object](#org00b97bd) + 6. [get(path, dst, options) ==> String|Stream|Buffer](#org2884287) + 7. [fastGet(remotePath, localPath, options) ===> string](#orga45add1) + 8. [put(src, remotePath, options) ==> string](#org2626fbc) + 9. [fastPut(localPath, remotePath, options) ==> string](#org335404a) + 10. [append(input, remotePath, options) ==> string](#orgb9ee3ef) + 11. [mkdir(path, recursive) ==> string](#org412944a) + 12. [rmdir(path, recursive) ==> string](#orga691434) + 13. [delete(path) ==> string](#orgf7895e3) + 14. [rename(fromPath, toPath) ==> string](#org395890b) + 15. [chmod(path, mode) ==> string](#orgcc4689b) + 16. [realPath(path) ===> string](#orge11a04a) + 17. [cwd() ==> string](#org1c19091) + 18. [uploadDir(srcDir, dstDir) ==> string](#orgfc30380) + 19. [downloadDir(srcDir, dstDir) ==> string](#orge333726) + 20. [end() ==> boolean](#orge3be768) + 21. [Add and Remove Listeners](#org5f565fe) +6. [FAQ](#org8addda4) + 1. [Remote server drops connections with only an end event](#org9ee0fe5) + 2. [How can you pass writable stream as dst for get method?](#org5b88fcf) + 3. [How can I upload files without having to specify a password?](#org1a40dd2) + 4. [How can I connect through a Socks Proxy](#org5ea739a) + 5. [Timeout while waiting for handshake or handshake errors](#orgeca0192) +7. [Examples](#org685d435) +8. [Change Log](#org300efa6) + 1. [v5.0.1 (Prod Version)](#orgbf51457) + 2. [v5.0.0](#org8067171) + 3. [v4.3.1](#orgbe31953) + 4. [v4.3.0](#org2672577) + 5. [v4.2.4](#org58d52cc) + 6. [v4.2.3](#org50eb228) + 7. [v4.2.2](#orgc4d313e) + 8. [v4.2.1](#orgb3912a8) + 9. [v4.2.0](#orgdb5ae5f) + 10. [v4.1.0](#org80e78b7) + 11. [v4.0.4](#org502466f) + 12. [v4.0.3](#org29e248a) + 13. [v4.0.2](#org094c72b) + 14. [v4.0.0](#org70374a5) + 15. [v2.5.2](#orgfb4aefb) + 16. [v2.5.1](#orgb226859) + 17. [v2.5.0](#org6393f0c) + 18. [v2.4.3](#org1f26abe) + 19. [v2.4.2](#org22dd609) + 20. [v2.4.1](#orge33d48d) + 21. [v2.4.0](#org2975d91) + 22. [v2.3.0](#orgf9e7909) + 23. [v3.0.0 – deprecate this version](#org687d4f8) + 24. [v2.1.1](#orgbba11c7) + 25. [v2.0.1](#org6ee2cc9) + 26. [v1.1.0](#org83b1c28) + 27. [v1.0.5:](#org8358697) +9. [Troubleshooting](#org9b4d4f2) +10. [Logging Issues](#org092b7a0) +11. [Pull Requests](#orgd8e3289) +12. [Contributors](#orgdc69c9c) + + + # SSH2 SFTP Client @@ -90,14 +92,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 @@ -118,12 +120,12 @@ Node versions < 10.x are not supported. }); - + # Version 5.x - + ## Breaking Changes in Version 5.x @@ -152,7 +154,7 @@ Node versions < 10.x are not supported. occur during a call to end the connection. - + ### Error Event Handling @@ -248,7 +250,7 @@ want to end, then you can just ignore the error, perform any necessary cleanup work and exit successfully. - + ### Technical Details @@ -268,7 +270,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 @@ -284,7 +286,17 @@ reset to false in preparation for the next error. any local files in the directories. - + + +## Version 5.0.1 + +- The error checking was a little too stringent. The use of exist() to test + for file types had a problem when the user does not have read/execute + rights on the directory. Replaced with stat() method, which should avoid + this issue. + + + # Documentation @@ -295,7 +307,7 @@ All the methods will return a Promise, except for `on()` and `removeListener()`, which are typically only used in special use cases. - + ## Specifying Paths @@ -333,12 +345,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 @@ -377,7 +389,7 @@ client has thrown the error. }); - + ### connect(config) ===> SFTPstream @@ -447,7 +459,7 @@ available [here](https://github.com/mscdex/ssh2#user-content-client-methods) }); - + ### list(path, pattern) ==> Array[object] @@ -520,7 +532,7 @@ directory. anchor matches to the beginning/end of the string etc. - + ### exists(path) ==> boolean @@ -555,7 +567,7 @@ if it exists or false if it does not. }); - + ### stat(path) ==> object @@ -602,7 +614,7 @@ Returns the attributes associated with the object pointed to by `path`. }); - + ### get(path, dst, options) ==> String|Stream|Buffer @@ -663,7 +675,7 @@ better off using the `fastGet()` method. decompress a gzip file 'on the fly'. - + ### fastGet(remotePath, localPath, options) ===> string @@ -706,7 +718,7 @@ throughput. This is the simplest method if you just want to download a file. }); - + ### put(src, remotePath, options) ==> string @@ -759,7 +771,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 @@ -802,7 +814,7 @@ Uploads the data in file at `localPath` to a new file on remote server at }); - + ### append(input, remotePath, options) ==> string @@ -847,7 +859,7 @@ in to the file. }); - + ### mkdir(path, recursive) ==> string @@ -876,7 +888,7 @@ defaults to false. }); - + ### rmdir(path, recursive) ==> string @@ -906,7 +918,7 @@ action will fail. }); - + ### delete(path) ==> string @@ -931,7 +943,7 @@ Delete a file on the remote server. }); - + ### rename(fromPath, toPath) ==> string @@ -956,7 +968,7 @@ necessary permissions to modify the remote file. }); - + ### chmod(path, mode) ==> string @@ -984,7 +996,7 @@ directory. }); - + ### realPath(path) ===> string @@ -996,14 +1008,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 @@ -1069,7 +1081,7 @@ using the `on()` method. }); - + ### downloadDir(srcDir, dstDir) ==> string @@ -1135,7 +1147,7 @@ the `on()` method. }); - + ### end() ==> boolean @@ -1158,7 +1170,7 @@ resources. This function also removes all listeners associated with the client. }); - + ### Add and Remove Listeners @@ -1184,12 +1196,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 @@ -1219,7 +1231,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? @@ -1283,7 +1295,7 @@ bring them across before saving to local file system. }); - + ## How can I upload files without having to specify a password? @@ -1318,7 +1330,7 @@ configuration. } - + ## How can I connect through a Socks Proxy @@ -1352,7 +1364,7 @@ This solution was provided by @jmorino. // client is connected - + ## Timeout while waiting for handshake or handshake errors @@ -1367,7 +1379,7 @@ documentation for details. Getting these parameters correct usually resolves the issue. - + # Examples @@ -1378,14 +1390,22 @@ 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.1 (Prod Version) + +- Turn down error checking to be less stringent and handle situations + where user does not have read permission on parent directory. + + + -## v5.0.0 (Prod version) +## v5.0.0 - Added two new methods `uploadDir()` and `downloadDir()` - Removed deprecated `auxList()` method @@ -1402,7 +1422,7 @@ helping developers see how the module and API can be used. - Any error events fired during an `end()` call are now ignored. - + ## v4.3.1 @@ -1412,7 +1432,7 @@ helping developers see how the module and API can be used. causing uncaughtException erros and causing the process to exit. - + ## v4.3.0 @@ -1422,7 +1442,7 @@ helping developers see how the module and API can be used. `error.message`. - + ## v4.2.4 @@ -1431,7 +1451,7 @@ helping developers see how the module and API can be used. - Clarify documentation on get() method - + ## v4.2.3 @@ -1440,7 +1460,7 @@ helping developers see how the module and API can be used. - Clean up mkdir example - + ## v4.2.2 @@ -1448,7 +1468,7 @@ helping developers see how the module and API can be used. - Added additional examples in the `example` directory - + ## v4.2.1 @@ -1462,7 +1482,7 @@ helping developers see how the module and API can be used. debugging - + ## v4.2.0 @@ -1473,7 +1493,7 @@ helping developers see how the module and API can be used. - Added additional examples in `example` directory - + ## v4.1.0 @@ -1490,7 +1510,7 @@ helping developers see how the module and API can be used. - Add `cwd()` method - + ## v4.0.4 @@ -1498,7 +1518,7 @@ helping developers see how the module and API can be used. - Fix return value from `get()` - + ## v4.0.3 @@ -1506,14 +1526,14 @@ helping developers see how the module and API can be used. - Modify exists() to always return 'd' if path is '.' - + ## v4.0.2 - Fix some minor packaging issues - + ## v4.0.0 @@ -1531,7 +1551,7 @@ helping developers see how the module and API can be used. - Added the `removeListener()` method to compliment the existing `on()` method. - + ## v2.5.2 @@ -1539,21 +1559,21 @@ helping developers see how the module and API can be used. - 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 @@ -1561,7 +1581,7 @@ helping developers see how the module and API can be used. - fix connect promise if connection ends - + ## v2.4.2 @@ -1569,7 +1589,7 @@ helping developers see how the module and API can be used. - fix windows path - + ## v2.4.1 @@ -1577,7 +1597,7 @@ helping developers see how the module and API can be used. - bug fix - + ## v2.4.0 @@ -1590,7 +1610,7 @@ helping developers see how the module and API can be used. - Added new 'exists' method and re-factored mkdir/rmdir - + ## v2.3.0 @@ -1599,7 +1619,7 @@ helping developers see how the module and API can be used. - fix: `mkdir` file exists decision logic - + ## v3.0.0 – deprecate this version @@ -1607,7 +1627,7 @@ helping developers see how the module and API can be used. - fix: get readable not emitting data events in node 10.0.0 - + ## v2.1.1 @@ -1615,7 +1635,7 @@ helping developers see how the module and API can be used. - add: `get` or `put` method add extra options [pr#52](https://github.com/jyu213/ssh2-sftp-client/pull/52) - + ## v2.0.1 @@ -1625,14 +1645,14 @@ helping developers see how the module and API can be used. - 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: @@ -1640,7 +1660,7 @@ helping developers see how the module and API can be used. - change: remove `this.client.sftp` to `connect` function - + # Troubleshooting @@ -1681,7 +1701,7 @@ trying to determine if the issue is with the underlying `ssh2` and `ssh2-streams` modules. - + # Logging Issues @@ -1706,7 +1726,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 @@ -1726,7 +1746,7 @@ your pull request what level of change it represents i.e. bug. - + # Contributors