What is the difference between deleteDir, cleanWs, and 'WsCleanup' in Jenkins pipeline?

These have all been mentioned (for example in this SO question) for cleaning up the workspace in Jenkinsfile. However, it seems that some are obsolete or have slightly different function and I would like to understand which to use.

Of these, deleteDir is the most commonly mentioned, and apparently the others are just different syntaxes for invoking the Jenkins Workspace Cleanup Plugin.

What is the functional difference? Which is recommended?

deleteDir()
cleanWs()
step([$class: 'WsCleanup'])

Solution 1:

From the official documentation:

deleteDir: Recursively delete the current directory from the workspace. Recursively deletes the current directory and its contents. Symbolic links and junctions will not be followed but will be removed. To delete a specific directory of a workspace wrap the deleteDir step in a dir step.

So, deleteDir is a method of Workflow Basic Steps plugin (which is a component of Pipeline Plugin).

cleanWs: Delete workspace when build is done.

Seems to be that cleanWs() is just a new version of step([$class: 'WsCleanup']) from Workspace Cleanup Plugin.

As I understand, between deleteDir and cleanWs is a slightly difference: cleanWs has more options (like cleanWhenAborted, cleanWhenFailure, etc.) and it's more flexible to use, but it's recommended to use only when build is done (not sure if we can use it at the beginning of build execution). On the other side, we can use deleteDir step to wipe the workspace before build execution.

UPDATE 1:
The post build cleanWs step can also take into account the build status, that's why it should be used only after the build execution.
However, under ws-cleanup plugin there is preBuildCleanup step as well. You can check an example (DSL) with both preBuildCleanup and cleanWs on the plugin page.

UPDATE 2:
@aaron-d-marasco pointed out that it's better not to use deleteDir in a docker image. You can check the details in this open bug.