Add two howtos related to the migration to Semgrepignore v2 (#2012)

* Add two howtos related to the migration to Semgrepignore v2

* Update docs/kb/semgrep-code/deprecated-include-directive.md

Co-authored-by: s-santillan <[email protected]>

* Update Semgrepignore v2 specification to reflect upcoming change

* Delete migration guide for ':include' which no longer applies

* Update docs/kb/semgrep-code/semgrepignore-ignored.md

Co-authored-by: s-santillan <[email protected]>

* Update docs/semgrepignore-v2-reference.md

Co-authored-by: s-santillan <[email protected]>

---------

Co-authored-by: s-santillan <[email protected]>

Author: mjambon

docs/kb/semgrep-code/semgrepignore-ignored.md

@@ -0,0 +1,51 @@
+---
+tags:
+  - Semgrep CLI
+  - Semgrepignore
+description: Why am I getting findings in files that should be ignored?
+---
+
+# Why am I getting findings in files that should be ignored?
+
+If you don't have already a `.semgrepignore` file, refer to our
+[guide on how to exclude files from Semgrep
+scans](/docs/ignoring-files-folders-code). Otherwise, if
+you already have a `.semgrepignore` file, read on.
+
+Starting with Semgrep CE 1.112.0, the Semgrepignore specification has
+changed slightly to better align with Git and Gitignore and to offer
+more flexibility.
+The new specification is referred to as
+[Semgrepignore v2](/docs/semgrepignore-v2-reference).
+If you're getting findings in files that should have been
+ignored according to your `.semgrepignore` file, check the
+following:
+
+1. If you're using Git, check that the `.semgrepignore` file is at the
+   root of the Git project or at least is within the project.
+   `.semgrepignore` files can be placed in any folder in the project
+   and follow the same specification as `.gitignore` files,
+   which they extend.
+2. If you're not using Git, check that the `.semgrepignore` file
+   is in the folder passed on the `semgrep scan` command line.
+   For example, if the command is `semgrep scan foo/`, you must move
+   the `.semgrepignore` file from the current folder
+   to `foo/.semgrepignore`.
+
+To ensure you're using Semgrepignore v2, pass the flag
+`--semgrepignore-v2` to `semgrep scan` or to `semgrep
+ci`. To use the legacy Semgrepignore v1 implementation, use
+`--no-semgrepignore-v2`. These options are for troubleshooting the
+migration from v1 to v2. These flags will be removed when v2 becomes
+only implementation available.
+
+## Best practices
+
+* When scanning a whole project, run `semgrep` from the project root.
+* Place a `.semgrepignore` file at the project root.
+* Optionally, place `.semgrepignore` files in subfolders so as to keep the
+  exclusion patterns simple and to allow moving these subfolders
+  around without having to edit the file exclusion patterns.
+* Refer to the [Gitignore
+  specification](https://git-scm.com/docs/gitignore)
+  for the precise syntax and usage of `.semgrepignore` files.

docs/semgrepignore-v2-reference.md

@@ -153,8 +153,9 @@ testsuite/
 
 ## Semgrepignore pattern syntax
 
-In Semgrepignore v2, the pattern syntax conforms strictly to the
-[Gitignore pattern syntax](https://git-scm.com/docs/gitignore#_pattern_format).
+In Semgrepignore v2, the pattern syntax conforms to the
+[Gitignore pattern
+syntax](https://git-scm.com/docs/gitignore#_pattern_format).
 They are glob patterns which support `*` and `**` with their usual
 meanings. For example, pattern `**/tmp/*.js` matches paths `tmp/foo.js` and
 `src/tmp/bar.js`.
@@ -165,15 +166,21 @@ the pattern or any of its subfolders). For
 example, `/a` and `a/b` are anchored patterns but not `a/`. Please
 consult the Gitignore documentation for details.
 
-In Semgrepignore v1, the following exceptions to the Gitignore
+As a deviation from the Gitignore syntax, Semgrepignore syntax supports
+`:include` directives. `:include` followed by an unquoted file path
+relative to the path of folder of the source `.semgrepignore` file
+(the current folder in v1) inserts patterns from that file.
+A common use case is to insert the line `:include .gitignore` at the
+beginning of a `.semgrepignore` file so as to avoid duplicating the
+Gitignore patterns. Included files may not contain include
+directives.
+
+## Legacy Semgrepignore v1
+
+In Semgrepignore v1, the following exceptions to the v2
 specification apply:
 
 * unsupported: pattern negation with `!`
 * unsupported: character ranges such as `[a-z]`
-* extension:
-  `:include` followed by an unquoted file path relative to the path of
-  folder of the source `.semgrepignore` file (the current folder in v1)
-  will insert patterns read from that file. A common use case was
-  `:include .gitignore` but it has become unnecessary in v2 where
-  `.gitignore` files are consulted automatically.
-  Include directives are deprecated in v2.
+* only one `.semgrepignore` file is supported and it must be in the
+  current folder