Logging docs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -28,6 +28,11 @@ A clear and concise description of what you expected to happen.
 - Protocol used
 - Remote server version and name
 
+## Log
+
+Report the snippet of the log file containing the unexpected behaviour.
+If there is any information you consider to be confidential, shadow it.
+
 ## Additional information
 
 Add any other context about the problem here.

CHANGELOG.md

@@ -33,6 +33,9 @@ Released on FIXME: ??
   - Select a file with `<M>`, the file when selected will have a `*` prepended to its name
   - Select all files in the current directory with `<CTRL+A>`
   - Read more on manual: [Work on multiple files](docs/man.md#Work-on-multiple-files-)
+- **Logging**:
+  - termscp now writes a log file, useful to debug and to contribute to fix issues.
+  - Read more on [manual](docs/man.md)
 - **File transfer changes**
   - *SFTP*
     - Added **COPY** command to SFTP (Please note that Copy command is not supported by SFTP natively, so here it just uses the `cp` shell command as it does in SCP).

CONTRIBUTING.md

@@ -61,6 +61,7 @@ Don't set other labels to your issue, not even priority.
 
 When you open a bug try to be the most precise as possible in describing your issue. I'm not saying you should always be that precise, since sometimes it's very easy for maintainers to understand what you're talking about. Just try to be reasonable to understand sometimes we might not know what you're talking about or we just don't have the technical knowledge you might think.
 Please always provide the environment you're working on and consider that we don't provide any support for older version of termscp, at least for those not classified as LTS (if we'll ever have them).
+If you can, provide the log file or the snippet involving your issue. You can find in the [user manual](docs/man.md) the location of the log file.
 Last but not least: the template I've written must be used. Full stop.
 
 Maintainers will may add additional labels to your issue:
@@ -68,7 +69,7 @@ Maintainers will may add additional labels to your issue:
 - **duplicate**: the issue is duplicated; the reference to the related issue will be added to your description. Your issue will be closed.
 - **priority**: this must be fixed asap
 - **sorcery**: it is not possible to find out what's causing your bug, nor is reproducible on our test environments.
-- **wontfix**: your bug has a very high ratio between the probability to encounter it and the difficult to fix it, or it just isn't a bug, but a feature.
+- **wontfix**: your bug has a very high ratio between the difficulty to fix it and the probability to encounter it, or it just isn't a bug, but a feature.
 
 ### Feature requests
 

docs/man.md

@@ -15,6 +15,7 @@
     - [File Explorer Format](#file-explorer-format)
   - [Text Editor ✏](#text-editor-)
     - [How do I configure the text editor 🦥](#how-do-i-configure-the-text-editor-)
+  - [Logging 🩺](#logging-)
 
 ---
 
@@ -25,6 +26,7 @@ termscp can be started with the following options:
 `termscp [options]... [protocol://user@address:port:wrkdir] [local-wrkdir]`
 
 - `-P, --password <password>` if address is provided, password will be this argument
+- `-q, --quiet` Disable logging
 - `-v, --version` Print version info
 - `-h, --help` Print help page
 
@@ -266,3 +268,33 @@ Just a reminder: **you can edit only textual file**; binary files are not suppor
 ### How do I configure the text editor 🦥
 
 Text editor is automatically found using this [awesome crate](https://github.com/milkey-mouse/edit), if you want to change the text editor to use, change it in termscp configuration. [Read more](#configuration-️)
+
+---
+
+## Logging 🩺
+
+termscp writes a log file for each session, which is written at
+
+- `$HOME/.config/termscp/termscp.log` on Linux/BSD
+- `$HOME/Library/Application Support/termscp/termscp.log` on MacOs
+- `FOLDERID_RoamingAppData\termscp\termscp.log` on Windows
+
+the log won't be rotated, but will just be truncated after each launch of termscp, so if you want to report an issue and you want to attach your log file, keep in mind to save the log file in a safe place before using termscp again.
+The log file always reports in *trace* level, so it is kinda verbose.
+I know you might have some questions regarding log files, so I made a kind of a Q/A:
+
+> Is it possible to reduce verbosity?
+
+No. The reason is quite simple: when an issue happens, you must be able to know what's causing it and the only way to do that, is to have the log file with the maximum verbosity level set.
+
+> If trace level is set for logging, is the file going to reach a huge size?
+
+Probably not, unless you never quit termscp, but I think that's likely to happne. A long session may produce up to 10MB of log files (I said a long session), but I think a normal session won't exceed 2MB.
+
+> I don't want logging, can I turn it off?
+
+Yes, you can. Just start termscp with `-q or --quiet` option. You can alias termscp to make it persistent. Remember that logging is used to diagnose issues, so since behind every open source project, there should always be this kind of mutual help, keeping log files might be your way to support the project 😉. I don't want you to feel guilty, but just to say.
+
+> Is logging safe?
+
+If you're concerned about security, the log file doesn't contain any plain password, so don't worry and exposes the same information the sibling file `bookmarks` reports.