56

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'])
Joshua Fox
  • 18,704
  • 23
  • 87
  • 147
  • 3
    See https://stackoverflow.com/questions/37468455/jenkins-pipeline-wipe-out-workspace – Ori Marko Jan 03 '19 at 09:09
  • 2
    Thank you. I added a link to that question (which was actually my trigger for asking my here.) That question mentions these, but does not state the *difference* between these options. – Joshua Fox Jan 03 '19 at 09:20
  • My question already linked to that other question and added a request for more info. I edited to further clarify what additional info I am looking for – Joshua Fox Nov 12 '19 at 13:28

1 Answers1

44

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.

biruk1230
  • 3,042
  • 4
  • 16
  • 29
  • 5
    FYI - `deleteDir` (haven't tried `cleanWs`) does bad things in a docker context at the top level of the WS; do don't do that. Use something like `sh("rm -rf *")` instead. – Aaron D. Marasco Sep 28 '19 at 23:27
  • 2
    @AaronD.Marasco could you elaborate more on the _bad things_ that `deleteDir` does when run at the top level of the WS ? – Jidehem Nov 21 '19 at 10:00
  • 3
    @Jidehem - bug open since 02/2017 - https://issues.jenkins-ci.org/browse/JENKINS-41894 . Basically, docker gets confused because the mounted directory went away. – Aaron D. Marasco Nov 22 '19 at 00:15
  • 1
    Any idea why `cleanWs()` is not recommended to be used at the beginning of a pipeline? – Arghya Jun 20 '20 at 17:40
  • @Arghya Seems to be that it's due to the following reason: the post build `cleanWs()` step can also take into account the build status. However, under **ws-cleanup** plugin there is `preBuildCleanup()` method as well. You can check an example on the plugin page: https://plugins.jenkins.io/ws-cleanup/ – biruk1230 Jun 20 '20 at 22:33
  • No I meant why can't we use `cleanWs()` right at the start and then do the build steps? `preBuildCleanup()` seems like a good option though. – Arghya Jun 22 '20 at 17:29
  • @Arghya Maybe if we'll use `cleanWs()` without options for checking build status (like `cleanWhenAborted`), then it could be working. But again, I'm not sure if it will not crash due to some internal build status checks ( I mean, that cases when `cleanWs()` tries to check the build status before the build was started). – biruk1230 Jun 22 '20 at 18:55