diff --git a/content/docs/command-reference/exp/init.md b/content/docs/command-reference/exp/init.md index 1596bf390d..447267479f 100644 --- a/content/docs/command-reference/exp/init.md +++ b/content/docs/command-reference/exp/init.md @@ -1,7 +1,7 @@ # exp init Initializes experiments. - + ## Synopsis ```usage @@ -15,22 +15,23 @@ usage: dvc exp init [-h] [-q | -v] [--run] [--interactive] [-f] ## Description -`dvc exp init` helps you quickly get started with experiments, with the command to -run and tracks data, params, source code, models, metrics and plots by default. +`dvc exp init` helps you quickly get started with experiments, with the command +to run and tracks data, params, source code, models, metrics and plots by +default. It reduces boilerplate for initializing [pipeline](/doc/command-reference/dag) stages in a `dvc.yaml` file by assuming sane defaults about the location of your -data, parameters, source code, models, metrics and plots, which can be customized -through config. +data, parameters, source code, models, metrics and plots, which can be +customized through config. -It also offers guided `--interactive` mode for creating a stage to be `exp run` later. -`dvc exp init` supports creating different types of stages, eg: live if you are using -dvclive to track metrics and plots, etc. +It also offers guided `--interactive` mode for creating a stage to be `exp run` +later. `dvc exp init` supports creating different types of stages, eg: live if +you are using dvclive to track metrics and plots, etc. ### The `command` argument -The `command` argument is optional, if you are using `--interactive` mode. -The `command` sent to `dvc exp init` can be anything your terminal would accept and +The `command` argument is optional, if you are using `--interactive` mode. The +`command` sent to `dvc exp init` can be anything your terminal would accept and run directly, for example a shell built-in, expression, or binary found in `PATH`. Please remember that any flags sent after the `command` are interpreted by the command itself, not by `dvc exp init`. @@ -49,55 +50,68 @@ $ dvc exp init "./a_script.sh > /dev/null 2>&1" $ dvc exp init './another_script.sh $MYENVVAR' ``` - ## Options -- `-i`, `--interactive` - prompts user for the command to execute and different paths for tracking - outputs and dependencies, unless they are provided through cli arguments explicitly. Interactive mode allows - users to set those location from default values or omit them. +- `-i`, `--interactive` - prompts user for the command to execute and different + paths for tracking outputs and dependencies, unless they are provided through + cli arguments explicitly. Interactive mode allows users to set those location + from default values or omit them. -- `--explicit` - `dvc exp init` assumes default location of your outputs and dependencies (which can be - overriden from the config). By using `--explicit`, it will not use those default values while initializing - experiments. - In `--interactive` mode, prompt won't set default value and all the values for the prompt needs to be explicitly provided, or omitted. +- `--explicit` - `dvc exp init` assumes default location of your outputs and + dependencies (which can be overriden from the config). By using `--explicit`, + it will not use those default values while initializing experiments. In + `--interactive` mode, prompt won't set default value and all the values for + the prompt needs to be explicitly provided, or omitted. -- `--code` - override the a path to your source file or directory which your experiment depends on. - The default is `src` directory for your code. +- `--code` - override the a path to your source file or directory which your + experiment depends on. The default is `src` directory for your code. -- `--data` - override the path to your data file or directory to track, which your experiment depends on. - The default is `data` directory. +- `--data` - override the path to your data file or directory to track, which + your experiment depends on. The default is `data` directory. -- `--model` - override the path to your models file or directory to track, which your experiment depends on. - `dvc exp init` assumes `models` directory by default. +- `--model` - override the path to your models file or directory to track, which + your experiment depends on. `dvc exp init` assumes `models` directory by + default. -- `--params` - override the path to [parameter dependencies](/doc/command-reference/params) which your experiment depends on. - The default parameters file name is `params.yaml`. Note that `dvc exp init` may fail if the parameters file does not exist - at the time of the invocation. +- `--params` - override the path to + [parameter dependencies](/doc/command-reference/params) which your experiment + depends on. The default parameters file name is `params.yaml`. Note that + `dvc exp init` may fail if the parameters file does not exist at the time of + the invocation. -- `--metrics` - override the path to metrics file to track, which your experiment produces. Default is `metrics.json` file. +- `--metrics` - override the path to metrics file to track, which your + experiment produces. Default is `metrics.json` file. -- `--plots` - override the path to plots file or directory, which your experiment produces. The default is `plots`. +- `--plots` - override the path to plots file or directory, which your + experiment produces. The default is `plots`. -- `--live` - override the directory `path` for [DVCLive](/doc/dvclive/user-guide/dvclive-with-dvc), which your experiment will write logs to. - The default is `dvclive` directory, which only comes to effect when used with `--type=live`. +- `--live` - override the directory `path` for + [DVCLive](/doc/dvclive/user-guide/dvclive-with-dvc), which your experiment + will write logs to. The default is `dvclive` directory, which only comes to + effect when used with `--type=live`. -- `--type` - selects the type of the stage to create. Currently it provides two different kinds of stages: `default` and `live`. - If unspecified, `default` stage is created. - - `default` stage creates a stage with `metrics` and `plots` tracked by DVC itself, - and does not track live-created artifacts (unless explicitly specified). +- `--type` - selects the type of the stage to create. Currently it provides two + different kinds of stages: `default` and `live`. If unspecified, `default` + stage is created. - With `--type=live`, `dvc exp init` will create a stage where `metrics` and `plots` are tracked - by `dvclive` itself (unless `--metrics` and `--plots` are explicitly provided). + `default` stage creates a stage with `metrics` and `plots` tracked by DVC + itself, and does not track live-created artifacts (unless explicitly + specified). -- `-n `, `--name ` - specify a custom name for the stage - generated by this command (e.g. `-n train`). By default, the name of the stage depends on `--type` of the - stage that is being created. If `--type=default, the name of the stage will be `default`, and in case of - `--type=live`, the name of the stage will be `live`. + With `--type=live`, `dvc exp init` will create a stage where `metrics` and + `plots` are tracked by `dvclive` itself (unless `--metrics` and `--plots` are + explicitly provided). - Note that the stage name can only contain letters, numbers, dash `-` and underscore `_`. +- `-n `, `--name ` - specify a custom name for the stage generated + by this command (e.g. `-n train`). By default, the name of the stage depends + on `--type` of the stage that is being created. If + `--type=default, the name of the stage will be `default`, and in case of `--type=live`, the name of the stage will be `live`. -- `-f`, `--force` - overwrite an existing stage in `dvc.yaml` file without asking for confirmation. + Note that the stage name can only contain letters, numbers, dash `-` and + underscore `_`. + +- `-f`, `--force` - overwrite an existing stage in `dvc.yaml` file without + asking for confirmation. - `--run` - runs the experiment after initializing it. @@ -119,4 +133,5 @@ $ dvc exp init './another_script.sh $MYENVVAR' #### Default stage #### Dvclive stage + diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json