Moving Working Docs to Current (#234)

You can preview the docs here: https://hayleycd.github.io/osv-scanner/
Updating docs for the new release.

docs/current/output.md

@@ -4,12 +4,75 @@ title: Output
 permalink: /output/
 nav_order: 5
 ---
-## JSON output
-By default osv-scanner outputs a human readable table. To have osv-scanner output JSON instead, pass the `--json` flag when calling osv-scanner.
+## Output formats
 
-When using the --json flag, only the JSON output will be printed to stdout, with all other outputs being directed to stderr. So to save only the json output to file, you can redirect the output with `osv-scanner --json ... > /path/to/file.json`
+You can control the format used by the scanner to output results with the `--format` flag.
 
-### Output Format
+### Table (Default)
+
+The default format, which outputs the results as a human-readable table.
+
+```bash
+osv-scanner --format table your/project/dir
+```
+
+<details markdown="1">
+<summary><b>Sample table output</b></summary>
+
+```bash
+╭─────────────────────────────────────┬───────────┬──────────────────────────┬─────────┬────────────────────╮
+│ OSV URL (ID IN BOLD)                │ ECOSYSTEM │ PACKAGE                  │ VERSION │ SOURCE             │
+├─────────────────────────────────────┼───────────┼──────────────────────────┼─────────┼────────────────────┤
+│ https://osv.dev/GHSA-c3h9-896r-86jm │ Go        │ github.com/gogo/protobuf │ 1.3.1   │ path/to/go.mod     │
+│ https://osv.dev/GHSA-m5pq-gvj9-9vr8 │ crates.io │ regex                    │ 1.3.1   │ path/to/Cargo.lock │
+╰─────────────────────────────────────┴───────────┴──────────────────────────┴─────────┴────────────────────╯
+```
+</details>
+
+---
+
+### Markdown Table
+
+```bash
+osv-scanner --format markdown your/project/dir
+```
+
+<details markdown="1">
+<summary><b>Sample markdown output</b></summary>
+
+**Raw output:**
+
+```
+| OSV URL | Ecosystem | Package | Version | Source |
+| --- | --- | --- | --- | --- |
+| https://osv.dev/GHSA-c3h9-896r-86jm<br/>https://osv.dev/GO-2021-0053 | Go | github.com/gogo/protobuf | 1.3.1 | ../scorecard-check-osv-e2e/go.mod |
+| https://osv.dev/GHSA-m5pq-gvj9-9vr8<br/>https://osv.dev/RUSTSEC-2022-0013 | crates.io | regex | 1.5.1 | ../scorecard-check-osv-e2e/sub-rust-project/Cargo.lock |
+```
+
+**Rendered:**
+
+| OSV URL | Ecosystem | Package | Version | Source |
+| --- | --- | --- | --- | --- |
+| https://osv.dev/GHSA-c3h9-896r-86jm<br/>https://osv.dev/GO-2021-0053 | Go | github.com/gogo/protobuf | 1.3.1 | ../scorecard-check-osv-e2e/go.mod |
+| https://osv.dev/GHSA-m5pq-gvj9-9vr8<br/>https://osv.dev/RUSTSEC-2022-0013 | crates.io | regex | 1.5.1 | ../scorecard-check-osv-e2e/sub-rust-project/Cargo.lock |
+
+</details>
+
+---
+
+### JSON
+
+```bash
+osv-scanner --format json your/project/dir
+```
+
+Outputs the results as a JSON object to stdout, with all other output being directed to stderr - this makes it safe to redirect the output to a file with
+```bash
+osv-scanner --format json -L path/to/lockfile > /path/to/file.json
+```
+
+<details markdown="1">
+<summary><b>Sample JSON output</b></summary>
 
 ```json
 {
@@ -98,4 +161,6 @@ When using the --json flag, only the JSON output will be printed to stdout, with
     }
   ]
 }
-```
+```
+
+</details>

docs/current/usage.md

@@ -4,52 +4,64 @@ title: Usage
 permalink: /usage/
 nav_order: 3
 ---
-OSV-Scanner collects a list of dependencies and versions that are used in your project, before matching this list against the OSV database via the [OSV.dev API](https://osv.dev#use-the-api). To build the list of dependencies, you can point OSV-Scanner at your project directory, or manually pass in the path to individual manifest files.
+## Usage
 
-### Scan a directory
+OSV-Scanner parses lockfiles, SBOMs, and git directories to determine your project's open source dependencies. These dependencies are matched against the OSV database via the [OSV.dev API](https://osv.dev#use-the-api) and known vulnerabilities are returned to you in the output. 
 
-Walks through a list of directories to find:
+### General use case: scanning a directory
 
-- Lockfiles
-- SBOMs
-- git directories for the latest commit hash
+```bash
+osv-scanner -r /path/to/your/dir
+```
 
-which is used to build the list of dependencies to be matched against OSV vulnerabilities.
+The preceding command will find lockfiles, SBOMs, and git directories in your target directory and use them to determine the dependencies to check against the OSV database for any known vulnerabilities.
 
-Can be configured to recursively walk through subdirectories with the `--recursive` / `-r` flag.
+The recursive flag `-r` or `--recursive` will tell the scanner to search all subdirectories in addition to the specified directory. It can find additional lockfiles, dependencies, and vulnerabilities. If your project has deeply nested subdirectories, a recursive search may take a long time. 
 
-Searching for git commit hash is intended to work with projects that use
-git submodules or a similar mechanism where dependencies are checked out
-as real git repositories.
+Git directories are searched for the latest commit hash. Searching for git commit hash is intended to work with projects that use git submodules or a similar mechanism where dependencies are checked out as real git repositories. 
 
-#### Example
+### Ignored files
+
+By default, OSV-Scanner will not scan files that are ignored by `.gitignore` files. All recursively scanned files are matched to a git repository (if it exists) and any matching `.gitignore` files within that repository are taken into account.
+
+There is a [known issue](https://github.com/google/osv-scanner/issues/209) that the parser does not correctly respect repository boundaries.
+
+The `--no-ignore` flag can be used to force the scanner to scan ignored files.
+
+### Specify SBOM
+
+If you want to check for known vulnerabilities only in dependencies in your SBOM, you can use the following command:
 
 ```bash
-osv-scanner -r /path/to/your/dir
+osv-scanner --sbom=/path/to/your/sbom.json
 ```
 
-### Input an SBOM
-
 [SPDX] and [CycloneDX] SBOMs using [Package URLs] are supported. The format is
 auto-detected based on the input file contents.
 
 [SPDX]: https://spdx.dev/
 [CycloneDX]: https://cyclonedx.org/
 [Package URLs]: https://github.com/package-url/purl-spec
 
-#### Example
+### Specify Lockfile(s)
+If you want to check for known vulnerabilities in specific lockfiles, you can use the following command:
 
 ```bash
-osv-scanner --sbom=/path/to/your/sbom.json
+osv-scanner --lockfile=/path/to/your/package-lock.json --lockfile=/path/to/another/Cargo.lock
 ```
 
-### Input a lockfile
+It is possible to specify more than one lockfile at a time; you can also specify how to parse an arbitrary file:
+
+```bash
+osv-scanner --lockfile 'requirements.txt:/path/to/your/extra-requirements.txt'
+```
 
 A wide range of lockfiles are supported by utilizing this [lockfile package](https://github.com/google/osv-scanner/tree/main/pkg/lockfile). This is the current list of supported lockfiles:
 
 - `buildscript-gradle.lockfile`
 - `Cargo.lock`
 - `composer.lock`
+- `conan.lock`
 - `Gemfile.lock`
 - `go.mod`
 - `gradle.lockfile`
@@ -63,16 +75,28 @@ A wide range of lockfiles are supported by utilizing this [lockfile package](htt
 - `pubspec.lock`
 - `requirements.txt`[\*](https://github.com/google/osv-scanner/issues/34)
 - `yarn.lock`
-- `/lib/apk/db/installed` (Alpine)
 
-#### Example
+The scanner also supports:
+- `installed` files used by the Alpine Package Keeper (apk) that typically live at `/lib/apk/db/installed`
+- `status` files used by the Debian Package manager (dpkg) that typically live at `/var/lib/dpkg/status`
+
+however you must specify them explicitly using the `--lockfile` flag:
 
 ```bash
-osv-scanner --lockfile=/path/to/your/package-lock.json --lockfile=/path/to/another/Cargo.lock
+osv-scanner --lockfile 'apk-installed:/lib/apk/db/installed'
+osv-scanner --lockfile 'dpkg-status:/var/lib/dpkg/status'
 ```
 
-### Scanning a Debian based docker image packages (preview)
+If the file you are scanning is located in a directory that has a colon in its name,
+you can prefix the path to just a colon to explicitly signal to the scanner that
+it should infer the parser based on the filename:
 
+```bash
+osv-scanner --lockfile ':/path/to/my:projects/package-lock.json'
+```
+### Scanning a Debian based docker image packages
+Preview
+{: .label } 
 This tool will scrape the list of installed packages in a Debian image and query for vulnerabilities on them.
 
 Currently only Debian based docker image scanning is supported.
@@ -106,4 +130,4 @@ appropriate osv-scanner flags:
 
 ```bash
 docker run -it -v ${PWD}:/src ghcr.io/google/osv-scanner -L /src/go.mod
-```
+```

docs/working_docs/usage.md

@@ -99,8 +99,9 @@ it should infer the parser based on the filename:
 osv-scanner --lockfile ':/path/to/my:projects/package-lock.json'
 ```
 
-### Scanning a Debian based docker image packages (preview)
-
+### Scanning a Debian based docker image packages
+Preview
+{: .label } 
 This tool will scrape the list of installed packages in a Debian image and query for vulnerabilities on them.
 
 Currently only Debian based docker image scanning is supported.