skip to content

In Allure 2, what happens when `allure generate` targets a report directory that already exists and is not empty, and what does `-c/--clean` change?

level: middleimportance: should knowfreq 52%

answer

  1. it refuses before it writes
  2. the error names the flag to add
  3. delete, not merge
  4. the second CI run fails
  5. in Allure 3 that letter means config

basics

~20 s

Allure 2 refuses: it logs that the target directory is already in use, tells you to add --clean, and exits with a failure code. With -c/--clean it deletes the whole report directory first, then generates. It overwrites, it does not merge.

solid answer

~40 s

Allure 2's `generate` checks the destination before it writes. If the directory exists and is not empty it logs an error saying the target directory is already in use and to add a `--clean` option, and returns a failure exit code without generating anything. Passing `-c` or `--clean` deletes that directory outright and then generates into it, so nothing from the previous report survives -- it is a delete, not a merge of old and new pages. An existing but empty directory is fine either way. This bites in CI whenever a workspace is reused between runs: the first run succeeds, the second fails on a stale `allure-report`. Note the version trap -- Allure 3's `generate` has no `--clean`, and there `-c` means `--config`.

code

bash · 2 lines
bash
allure generate ./allure-results -o ./allure-report
allure generate ./allure-results -o ./allure-report --clean

go deeper

for a junior

Remember that regenerating into a directory that already has a report in it fails, and that the flag to add is --clean on the generate command.

for a middle

Explain the guard itself: exists and non-empty means refuse and exit non-zero, and the flag switches that to delete-then-generate rather than to a merge.

for a senior

Talk about the CI shape -- reused workspaces, a step that must not swallow the exit code, and the risk of publishing a stale report when the failure goes unnoticed.

for a principal

Own the upgrade story: the same short option means clean in one major and config in the other, so flag audits belong in the migration plan rather than in the first red build.

## The check that runs before anything is written Allure 2's `generate` command does one guard before producing a report: 1. If the report directory **exists and `--clean` was passed**, the directory is deleted. 2. If the report directory **exists, is non-empty and `--clean` was not passed**, the command logs an error naming the target path and telling you to add a `--clean` option to overwrite, and returns a failure exit code. Nothing is generated. 3. Otherwise it generates. So the flag is not an optimisation or a tidy-up. It is the switch between *refuse* and *overwrite*, and without it a second generation into the same path is a hard failure. ## Why the refusal exists A report directory is a set of files that reference one another -- an `index.html`, a bundle, and the data files the page loads. Writing a new report on top of an old one without removing it leaves whichever files the new run did not happen to replace. Those orphans are not inert: the page can end up loading a mixture of two runs, which is far worse than a missing report because it looks like a report. Refusing an occupied directory and offering a destructive flag is the safe pair of behaviours, and it makes the failure loud at generation time instead of quiet at reading time. ## What `--clean` does and does not do - It **deletes the report directory** and everything under it, then generates. - It does **not** merge, patch or diff anything against the previous report. - It does **not** touch the results directory, which is the input and is left exactly as it was. - It is **not** required when the destination does not exist, which is the normal case in a fresh CI workspace. The commonest misconception is that `--clean` is about keeping the report tidy or about trend data. It is neither. Anything you want to carry from the previous report into the next one has to be arranged before generation, by putting it where the generator will read it; the flag itself only ever removes. ## The version trap on the short option This is where the two live majors diverge, and it is worth memorising because the same letter means two different things: | | Allure 2 (2.47) | Allure 3 (3.16.1) | |---|---|---| | `-c` on `generate` | `--clean` -- delete the report directory | `--config` -- path to the config file | | long form of config | `--config`, with `--configDirectory` and `--profile` | `--config`, alongside the `allurerc` discovered in the working directory | | non-empty destination | refuses unless `--clean` is passed | written into; no such guard | A script that carries `-c` across an upgrade therefore does not break loudly -- it quietly becomes a config-path option missing its argument, or consumes the next token as a path. Migrating means re-reading the flags, not just the command names. ## Where it shows up in practice - **Reused CI workspaces.** A self-hosted runner or a cached workspace keeps `allure-report` between builds. The first build is green, the second fails at generation. The fix is `--clean` in the command, or deleting the directory as part of the step. - **Local iteration.** Regenerating while debugging a report hits the same guard within seconds of the first success, which is where most people meet it. - **Two suites, one destination.** Two generation commands writing into one directory is not a way to combine reports. Passing several results directories to a single `generate` is; `generate` accepts more than one positional results path and merges them into one report. - **`allure serve` never hits it.** Serve generates into a freshly created temporary directory, so there is nothing to collide with -- which is why people who only ever use `serve` have never seen the error. ## What a good answer sounds like State the behaviour first -- it refuses and exits non-zero -- then what the flag changes, then the fact that it is a delete rather than a merge, then the version note that Allure 3 does not have the flag and rebinds the letter. That ordering answers the question asked before volunteering the trivia, and the exit-code detail is the part that matters in a pipeline, because a build that ignores it will publish yesterday's report.

  • Your CI step runs generation without `--clean` and the build has started failing on the second run of every reused workspace. What do you change?
    Either add `--clean` so generation owns the directory, or delete the report directory in the step before it. Prefer the flag: it keeps the behaviour with the command that depends on it. Also check the step is not silently ignoring the failure exit code, or the job will publish the previous run's report as if it were current.
  • Does `--clean` affect anything in the results directory?
    No. It only deletes the report directory. The results directory is the input, is read and never written by generation, and is what you keep if you want the ability to regenerate the report later.

saying these in an interview costs you the question

  • Thinks --clean merges old and new report pages
  • Assumes generation silently overwrites an existing report
  • Thinks --clean deletes the results directory
  • Carries -c across majors assuming it still means clean
  • Ignores the non-zero exit and publishes a stale report