From 9b36aaef8de3b0f4457da82b4f314d88c6c0d0c1 Mon Sep 17 00:00:00 2001
From: Gareth Jones <gareth.jones@shinetech.com>
Date: Mon, 1 May 2017 08:16:53 +1000
Subject: [PATCH] docs(file): added file appender docs

---
 docs/categoryFilter.md |  2 +-
 docs/file.md           | 47 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 docs/file.md

diff --git a/docs/categoryFilter.md b/docs/categoryFilter.md
index e80966c..f0c7763 100644
--- a/docs/categoryFilter.md
+++ b/docs/categoryFilter.md
@@ -4,7 +4,7 @@ This is not strictly an appender - it wraps around another appender and stops lo
 
 ## Configuration
 
-* `type` - `categoryFilter`
+* `type` - `"categoryFilter"`
 * `exclude` - `string | Array<string>` - the category (or categories if you provide an array of values) that will be excluded from the appender.
 * `appender` - `string` - the name of the appender to filter.
 
diff --git a/docs/file.md b/docs/file.md
new file mode 100644
index 0000000..01c348e
--- /dev/null
+++ b/docs/file.md
@@ -0,0 +1,47 @@
+# File Appender
+
+The file appender writes log events to a file. It supports an optional maximum file size, and will keep a configurable number of backups. When using the file appender, you should also call `log4js.shutdown` when your application terminates, to ensure that any remaining asynchronous writes have finished. Although the file appender uses the [streamroller](https://github.com/nomiddlename/streamroller) library, this is included as a dependency of log4js so you do not need to include it yourself.
+
+## Configuration
+
+* `type` - `"file"`
+* `filename` - `string` - the path of the file where you want your logs written.
+* `maxLogSize` - `integer` (optional) - the maximum size (in bytes) for the log file. If not specified, then no log rolling will happen.
+* `backups` - `integer` (optional, default value = 5) - the number of old log files to keep during log rolling.
+
+Any other configuration parameters will be passed to the underlying [streamroller](https://github.com/nomiddlename/streamroller) implementation (see also node.js core file streams):
+* `encoding` - `string` (default "utf-8")
+* `mode`- `integer` (default 0644)
+* `flags` - `string` (default 'a')
+* `compress` - `boolean` (default false) - compress the backup files during rolling (backup files will have `.gz` extension)
+
+## Example
+
+```javascript
+log4js.configure({
+  appenders: {
+    everything: { type: 'file', filename: 'all-the-logs.log' }
+  },
+  categories: {
+    default: { appenders: [ 'everything' ], level: 'debug' }
+  }
+});
+
+const logger = log4js.getLogger();
+logger.debug('I will be logged in all-the-logs.log');
+```
+
+This example will result in a single log file (`all-the-logs.log`) containing the log messages.
+
+## Example with log rolling (and compressed backups)
+```javascript
+log4js.configure({
+  appenders: {
+    everything: { type: 'file', filename: 'all-the-logs.log', maxLogSize: 10458760, backups: 3, compress: true }
+  },
+  categories: {
+    default: { appenders: [ 'everything' ], level: 'debug'}
+  }
+});
+```
+This will result in one current log file (`all-the-logs.log`). When that reaches 10Mb in size, it will be renamed and compressed to `all-the-logs.log.1.gz` and a new file opened called `all-the-logs.log`. When `all-the-logs.log` reaches 10Mb again, then `all-the-logs.log.1.gz` will be renamed to `all-the-logs.log.2.gz`, and so on.