Project: FOSSA (Provisioning / Security & Compliance)
File: differences-from-v1.md

Upgrading from FOSSA CLI 1.x to 3.x is a major breaking change. For most users, this change should be seamless. For users who use less common flags, or who have heavily customized their CLI usage, you may need to update some scripts. - - - - - - - - - - - - - - - - - - - Our focus in CLI 3.x is making FOSSA integrations easier to deploy by reducing the amount of configuration needed by users. Our goal is to get as close to turnkey deployment on as many build systems and codebases as possible. FOSSA 3.x supports following new build managers and languages: FOSSA CLI 3.x now does automatic analysis target discovery when you run `fossa analyze`. This means that `fossa init` is no longer required. `fossa init` is now a no-op that emits a warning, and will be removed in a future release. In 1.x, modules could be manually configured with "strategies" that specified how a module should be analyzed. While `fossa init` attempted to choose the best strategy, manual intervention was sometimes required depending on the project's setup. In 3.x, the CLI now automatically selects the optimal strategy for analysis targets given the current environment (e.g. whether a build tool is available). This is possible because discovery and analysis are now one step, so we can check the suitability of analysis strategies while discovering targets. With , 3.x supports: License scanning vendor dependencies <!-- markdown-link-check-disable-next-line --> Analyzing archives that are located at a specific web address (e.g. https://my-deps-source/v1.zip) Manually specifying dependency by it's name and license (e.g. my-custom-dep with MIT license) Manually specifying dependency for analysis by its name and dependency type (e.g. pip dependency: request) This is very useful when working with a package manager that is not supported, or when you have a custom and nonstandard dependency management solution. The FOSSA CLI will automatically read a fossa-deps.yml or a fossa-deps.json file in the root directory (usually the current working directory) when fossa analyze is run and parse dependencies from it. These dependencies will be added to the dependencies that are normally found when fossa analysis is run in the directory. Please refer to documentation for more details. Analysis strategies in CLI 3.x have substantive improvements in correctness and reliability across all language integrations. 3.x has much stronger compile-time correctness guarantees in its parsers, and uses build tool plugins instead of output parsing for target types where output parsing was brittle. CLI 3.x has much better debug logging, including a new feature called "replay logging" which allows developers to perfectly reproduce a bug report given a replay

This is made possible by stronger compile-time guarantees that ensure all effects that occur during analysis are logged for replay. In 1.x, the CLI was configured by "modules", which were entrypoints to user programs that the CLI should analyze. In 3.x, we've renamed "modules" to "analysis targets", and simplified how analysis targets are defined. We renamed analysis targets to avoid confusing naming conflicts with existing language-specific "modules". Analysis targets are no longer defined by multiple, confusingly similar fields (e.g. "Dir" vs. "Path"), and are now simple `(type, target)` tuples. FOSSA 3.x does not support following build managers: Bazel Debian Ant Bower Okbuck Buck For these managers, you can write a custom integration by creating `fossa-deps.{yml,json}` file which is more representative of your project's dependencies usage. Following CLI commands are not supported with 3.x: `fossa analyze --server-scan` `fossa analyze --dev` `fossa analyze --options` `fossa test --suppress-issues` `fossa upload` (this is supplemented by `fossa-deps.{yml,json}` file now, refer to "Migrate archive upload targets" section) `fossa report licences` (supplemented by `fossa report attribution --format json`) `fossa report dependencies` 3.x uses a new plugin-based strategy to perform discovery and analysis, it analyses all resolvable Gradle configurations. 3.x does not accept any options: `cmd`, `task`, `timeout`, `all-configurations`, `configuration`, `retries`, `online`, `all-submodules`, and any other option supported in 1.x for Gradle analysis. In 3.x, There is no timeout (analysis may run for a long time) All resolvable configurations are analyzed There are no retries (CLI will attempt to analyze the project once) Specific command and Gradle tasks can not be used in the analysis `$FOSSAGRADLECOMMAND` environment variable cannot be configured. 3.x uses Gradle executable in `$PATH`. Refer to for more information for gradle. 3.x performs the `lein deps :tree` strategy by default. 3.x does not support any options - `strategy`, and `lien` for Clojure analysis. Refer to for more information on how 3.x performs analysis for clojure. 3.x supports analysis of the Go project for projects using gomod, godeps, and glide. 3.x does not support following options: `tags`, `all-tags,` `strategy`, `lockfile`, `manifest`, `modules-vendor`, `allow-unresolved`, `allow-unresolved-prefix`, `allow-nested-vendor`, `allow-deep-vendor`, `allow-external-vendor`, `allow-external-vendor-prefix`. Refer to for more information on how 3.x performs analysis for Go. 3.x will apply stack strategy when a project is discovered having stack.yaml file 3.x will apply cabal-install strategy for projects using cabal.project or file with .cabal extension 3.x does not support `strategy` option for Haskell analysis Refer to for more information on how 3.x performs analysis for haskell. 3.x uses `mvn` command for analysis. `mvn` must be accessible in $PATH 3.x does not support any option: `strategy`, `cmd`, or `bin` for Maven analysis Refer to for more information on how 3.x performs analysis for maven. 3.x supports `yarn`, `npm`, and `package.json` for analysis. 3.x does not support the `strategy` option for Nodejs analysis. v2.x automatically selects the application strategy which yields the highest fidelity of dependency

Refer to for more information on how 3.x performs analysis for nodejs. 3.x does not support the `strategy` option for Nuget analysis. v2.x automatically selects the application strategy which yields the highest fidelity of dependency information. Refer to for more information on how 3.x performs analysis for nuget. Refer to for more information on how 3.x performs analysis for cocoapods. Refer to for more information on how 3.x performs analysis for carthage. Refer to for more information on how 3.x performs analysis for composer. 3.x automatically selects the application strategy which yields the highest fidelity of dependency information. 3.x uses attempts to infer requirements.txt for any file with prefix `req` in its name, and `txt` extension. 3.x does not support the `strategy` or `requirement` option for Python analysis. Refer to for more information on how 3.x performs analysis for python. 3.x attempts to use the `bundle show` command (`bundle` must be accessible from `$PATH`), and if it fails, it attempts to analyze dependencies from `Gemfile.lock` file. 3.x does not support `strategy` or `gemfile-lock-path` option for Gem Analysis. Refer to for more information on how 3.x performs analysis for gem. Refer to for more information on how 3.x performs analysis for cargo. 3.x requires `sbt` executable to be accessible from `$PATH` 3.x does not require a project to have a `net.virtual-void.sbt-dependency-graph` extension installed. Refer to for more information on how 3.x performs analysis for sbt. Since analysis targets are now automatically discovered during analysis, `fossa init` is no longer a valid command. `fossa init` is currently a no-op that emits a warning. It may be removed in a future release. We've made major breaking changes in the `.fossa.yml` file format for CLI 3.x to improve clarity. You'll need to migrate your 1.x `.fossa.yml` to the new 3.x format for their configurations to apply. `.fossa.yml` for 1.x will be ignored when running cli with version greater than 1.x. We determine whether a configuration file is compatible by examining its `version` field. .fossa.yml with version field value of `1` and `2` are for 1.x. .fossa.yml with version field value of `3` are for 3.x, and 2.x. For documentation on the new configuration file format, see In 1.x, were a special kind of manually specified module of type `archive` that uploaded source code to the FOSSA backend for license scanning. They were also known as "raw" modules or "license scan" modules. In 3.x, archive uploads are no longer a special analysis target type. Instead, you can use our general support for to specify local dependencies. If you run into migration issues, you can get support by opening a ticket in this

If you are integrating a private project and want to share more details, or if you're a FOSSA customer with priority support, you can you can file a ticket at for assistance. In 1.x, `fossa report` supported `fossa report dependencies`, `fossa report licenses` and `fossa report attribution`. In 3.x, only `fossa report attribution` is supported. The information in the previously supported v1 commands is contained in the output from `attribution`. This command also now requires a `--format` argument: see for details. The format for this report has also changed slightly. Until the end of April 2022, FOSSA supported a compatibilty script to convert the format of the report. For more information, including usage information, see in the user guide. FOSSA 1.x CLI is available and can be used indefinitely. We intend to make 3.x the default target for our installation scripts (as previously described in our documentation) in July 2022. If you wish to continue using 1.x, please migrate to using `install-v1` scripts. FOSSA will only patch 1.x for security fixes. Any feature and patch development work will occur in 3.x moving forth. If you run into poor dependency results with 3.x, you can get support by opening a ticket in this repository. If you are integrating a private project and want to share more details, or if you're a FOSSA customer with priority support, you can file a ticket at for assistance. You can configure to run specific analyzer or only analyze specific paths in `.fossa.yml` file. Please refer to documentation You can identify your cli version by performing `fossa --version` command. You can add `--debug` argument to your fossa commands (e.g. `fossa analyze --debug`), this will emit debug logs to stdout, and create `fossa.debug.json` in working directory. 1.x version, is first major release of fossa cli sourced at . 2.x version, is the second major release of fossa CLI sourced at . This release was not a default target of the installation script, provided on fossa's website. 3.x version, is third major releases. With this release: 3.x becomes default target for installation script provided at 3.x becomes default target for install-latest script provided at We migrates 2.x source code from to and releases it as 3.x. Archives [fossas/spectrometer] source code repository. 3.x will be released on November 12, 2021. Note: There are no breaking changes from 2.x to 3.x. The 3.x version in functional sense, continuation of 2.x version. The 3.x version was released to (1) match the `version` field of the fossa configuration file with the major release version of cli, (2) mark migration of CLI 2.x source code back into the fossa-cli repository, and (3) mark 3.x now the default target for installation for all fossa users moving forwards. If you were previously using the installation script provided at , it is now recommended to use the installation latest script provided at .