Merge pull request #58 from basil/docs

 Convert documentation to AsciiDoc; copyedit documentation

CHANGELOG.adoc

@@ -0,0 +1,154 @@
+= Changelog
+
+* All notable changes prior to 0.39 are documented in this changelog.
+* Release notes for versions >= 0.39 can be found on the https://github.com/jenkinsci/ws-cleanup-plugin/releases[GitHub releases page].
+
+== Release History
+
+=== Release 0.37 (2018-12-17)
+
+* Java 11 support was introduced in this release. Older versions do not support it.
+
+=== Release 0.35 (2018-10-11)
+
+* Introduce a way to disable deferred wipeout (https://github.com/jenkinsci/ws-cleanup-plugin/pull/37[#37], https://issues.jenkins.io/browse/JENKINS-53740[JENKINS-53740])
+
+=== Release 0.34 (2017-07-17)
+
+* Avoid using stale channel in disposable what node goes offline (https://github.com/jenkinsci/ws-cleanup-plugin/pull/33[#33])
+
+=== Release 0.33 (2017-04-24)
+
+* Add Pipeline-friendly syntax (https://github.com/jenkinsci/ws-cleanup-plugin/pull/30[#30])
+* Japanese localization (https://github.com/jenkinsci/ws-cleanup-plugin/pull/32[#32])
+* Fix inclusion/exclusion pattern layout (https://issues.jenkins.io/browse/JENKINS-43179[JENKINS-43179]
+
+=== Release 0.32 (2016-11-01)
+
+* Do not leak temporary directories that plugin failed to clean (https://issues.jenkins.io/browse/JENKINS-24824[JENKINS-24824])
+
+=== Release 0.30 (2016-06-24)
+
+* Pipeline support
+
+=== Release 0.27 (2015-08-19)
+
+* Adjust console logging
+* Add logging to track down https://issues.jenkins.io/browse/JENKINS-24824[JENKINS-24824]
+
+=== Release 0.26 (2015-05-29)
+
+* Require minimal width for pattern labels (https://issues.jenkins.io/browse/JENKINS-27103[JENKINS-27103])
+* Do not log exceptions on standard error
+
+=== Release 0.25 (2015-01-25)
+
+* Survives workspace rename failure during async delete (https://issues.jenkins.io/browse/JENKINS-26250[JENKINS-26250])
+
+=== Release 0.24 (2014-09-09)
+
+* Workspace is deleted asynchronously (https://issues.jenkins.io/browse/JENKINS-20056[JENKINS-20056] / https://github.com/jenkinsci/ws-cleanup-plugin/pull/20[#20])
+* Fixed some warnings and code style (https://github.com/jenkinsci/ws-cleanup-plugin/pull/19[#19])
+
+=== Release 0.23 (2014-08-26)
+
+* Proper escaping of file paths (https://github.com/jenkinsci/ws-cleanup-plugin/pull/17[#17])
+* Delete workspace fails (https://issues.jenkins.io/browse/JENKINS-23693[JENKINS-23693])
+
+=== Release 0.22 (2014-08-03)
+
+* Fixed environment variable expansion on nodes
+
+=== Release 0.21 (2014-06-23)
+
+* Don't follow symlinks (https://issues.jenkins.io/browse/JENKINS-13444[JENKINS-13444])
+* Workspace cleanup fails when some pattern is specified (https://issues.jenkins.io/browse/JENKINS-23494[JENKINS-23494])
+* External delete cmd doesn't work properly (https://issues.jenkins.io/browse/JENKINS-23523[JENKINS-23523])
+
+=== Release 0.20 (2014-02-01)
+
+* Fixed build status setting: if the workspace cleanup fails, build status is set to `FAILURE` (https://github.com/jenkinsci/ws-cleanup-plugin/pull/14[#14])
+
+=== Release 0.19 (2013-10-08)
+
+* Fixed problem with spaces in external cleanup command (https://github.com/jenkinsci/ws-cleanup-plugin/pull/13[#13])
+
+=== Release 0.18 (2013-09-15)
+
+* Fixed broken backward compatibility in pre-build cleanup (https://issues.jenkins.io/browse/JENKINS-19574[JENKINS-19574])
+
+=== Release 0.17 (2013-09-11)
+
+* Allow to configure external program to do the cleanup (https://github.com/jenkinsci/ws-cleanup-plugin/pull/12[#12])
+* Fixed German translation encoding (https://github.com/jenkinsci/ws-cleanup-plugin/pull/11[#11])
+
+=== Release 0.16 (2013-07-02)
+
+* Added ability to specify if the workspace should be wiped out in pre-build step via a job parameter (https://github.com/jenkinsci/ws-cleanup-plugin/pull/10[#10])
+
+=== Release 0.15 (2013-06-18)
+
+* Don't wait for previous build step to complete (https://github.com/jenkinsci/ws-cleanup-plugin/pull/9[#9])
+
+=== Release 0.14 (2013-05-14)
+
+* Fix backward compatibility issues (https://issues.jenkins.io/browse/JENKINS-17930[JENKINS-17930], https://issues.jenkins.io/browse/JENKINS-17940[JENKINS-17940])
+* Delete the workspace regardless on the job result by default (https://issues.jenkins.io/browse/JENKINS-17930[JENKINS-17930])
+* Fix configuration (https://issues.jenkins.io/browse/JENKINS-17761[JENKINS-17761])
+
+=== Release 0.13 (2013-05-03)
+
+* Configure deleting of workspace based on build status (https://github.com/jenkinsci/ws-cleanup-plugin/pull/7[#7])
+* German translation (https://github.com/jenkinsci/ws-cleanup-plugin/pull/6[#6])
+
+=== Release 0.12 (2013-02-16)
+
+* Retry delete 3 times in prebuild cleanup and add eventually error message into console log (https://github.com/jenkinsci/ws-cleanup-plugin/pull/5[#5])
+
+=== Release 0.11 (2013-01-23)
+
+* Added option not to fail the build if some error happens during the cleanup (https://issues.jenkins.io/browse/JENKINS-15236[JENKINS-15236])
+* Added option to cleanup matrix parent workspace (https://issues.jenkins.io/browse/JENKINS-14128[JENKINS-14128])
+
+=== Release 0.10 (2012-07-17)
+
+* Fixed skipping the cleanup: skip only when this option is checked (https://github.com/jenkinsci/ws-cleanup-plugin/pull/4[#4])
+
+=== Release 0.9 (2012-07-15)
+
+* Added option to skip the cleanup when build fails (https://github.com/jenkinsci/ws-cleanup-plugin/pull/3[pull#3])
+
+=== Release 0.8 (2012-03-14)
+
+* Ensure that workspace cleanup is run after all other plugins (https://issues.jenkins.io/browse/JENKINS-12962[JENKINS-12962])
+
+=== Release 0.7 (2011-12-07)
+
+* Check if workspace exists (https://issues.jenkins.io/browse/JENKINS-11998[JENKINS-11998])
+* Added possibility to delete also directories when delete pattern is specified (https://issues.jenkins.io/browse/JENKINS-11927[JENKINS-11927])
+* Added possibility to specify also exclude patterns (https://issues.jenkins.io/browse/JENKINS-11928[JENKINS-11928])
+* Added missing `Pattern` descriptor
+
+=== Release 0.6 (2011-10-11)
+
+* Workspace cleanup should be the first or the last step in case of pre-build or post-build cleanup, respectively (https://issues.jenkins.io/browse/JENKINS-11210[JENKINS-11210])
+
+=== Release 0.5 (2011-09-27)
+
+* Added possibility to delete only part of the workspace specified by Ant dir scanner pattern.
+
+=== Release 0.4 (2011-04-07)
+
+* Bug fix: checkbox for deleting workspace after the build was not showing up on the job config page
+
+=== Release 0.3 (2011-03-02)
+
+* Fix to delete right workspace when concurrent builds option is in use
+
+=== Release 0.2 (2011-02-28)
+
+* Add an option to delete workspace before build (requires Jenkins 1.399 or higher)
+
+=== Release 0.1 (2011-02-10)
+
+* Initial release

license.txt → LICENSE

@@ -1,4 +1,4 @@
-The MIT License
+MIT License
 
 Copyright (c) <2007> <Red Hat, Inc.>
 
@@ -9,14 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.adoc

@@ -0,0 +1,166 @@
+= Workspace Cleanup Plugin
+:toc:
+:toc-placement!:
+:toc-title:
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
+link:https://ci.jenkins.io/job/Plugins/job/ws-cleanup-plugin/job/master/[image:https://ci.jenkins.io/job/Plugins/job/ws-cleanup-plugin/job/master/badge/icon[Build Status]]
+link:https://github.com/jenkinsci/ws-cleanup-plugin/graphs/contributors[image:https://img.shields.io/github/contributors/jenkinsci/ws-cleanup-plugin.svg[Contributors]]
+link:https://plugins.jenkins.io/ws-cleanup[image:https://img.shields.io/jenkins/plugin/v/ws-cleanup.svg[Jenkins Plugin]]
+link:https://github.com/jenkinsci/ws-cleanup-plugin/releases/latest[image:https://img.shields.io/github/release/jenkinsci/ws-cleanup-plugin.svg?label=changelog[GitHub release]]
+link:https://plugins.jenkins.io/ws-cleanup[image:https://img.shields.io/jenkins/plugin/i/ws-cleanup.svg?color=blue[Jenkins Plugin Installs]]
+
+toc::[]
+
+== Introduction
+
+This plugin deletes the build workspace.
+
+== Getting started
+
+=== https://jenkins.io/doc/book/pipeline/[Pipeline] jobs
+
+There is a single https://www.jenkins.io/doc/pipeline/steps/ws-cleanup/[step] to be used whenever a workspace is allocated.
+
+=== Declarative Pipeline
+
+The `cleanWs` step is available for use with Declarative Pipeline.
+When you want to clean the workspace after the build, you can add this step under a suitable condition in the https://www.jenkins.io/doc/book/pipeline/syntax/#post[post] section of your Pipeline job.
+If you want to clean the workspace before the build starts, you need to add some extra configuration to be able to clean before the sources are checked out from SCM.
+See the examples below for details.
+
+The snippet generator that is built into Jenkins can assist you with what configuration options are available.
+Click on the **Pipeline Syntax** button in your Pipeline job and select `cleanWs` from the **Sample Step** drop-down.
+For example:
+
+[source,groovy]
+----
+pipeline {
+    agent any
+    options {
+        // This is required if you want to clean before build
+        skipDefaultCheckout(true)
+    }
+    stages {
+        stage('Build') {
+            steps {
+                // Clean before build
+                cleanWs()
+                // We need to explicitly checkout from SCM here
+                checkout scm
+                echo "Building ${env.JOB_NAME}..."
+            }
+        }
+    }
+    post {
+        // Clean after build
+        always {
+            cleanWs(cleanWhenNotBuilt: false,
+                    deleteDirs: true,
+                    disableDeferredWipeout: true,
+                    notFailBuild: true,
+                    patterns: [[pattern: '.gitignore', type: 'INCLUDE'],
+                               [pattern: '.propsfile', type: 'EXCLUDE']])
+        }
+    }
+}
+----
+
+=== Freestyle jobs
+
+The plugin provides a build wrapper (**Delete workspace before build starts**) and a post build step (**Delete workspace when build is done**).
+These steps allow you to configure which files will be deleted and in what circumstances.
+The post build step can also take the build status into account.
+
+This plugin also provides https://plugins.jenkins.io/job-dsl/[Job DSL] support for Freestyle jobs.
+For example:
+
+[source,groovy]
+----
+job("foo") {
+    wrappers {
+        preBuildCleanup { // Clean before build
+            includePattern('**/target/**')
+            deleteDirectories()
+            cleanupParameter('CLEANUP')
+        }
+    }
+    publishers {
+        cleanWs { // Clean after build
+            cleanWhenAborted(true)
+            cleanWhenFailure(true)
+            cleanWhenNotBuilt(false)
+            cleanWhenSuccess(true)
+            cleanWhenUnstable(true)
+            deleteDirs(true)
+            notFailBuild(true)
+            disableDeferredWipeout(true)
+            patterns {
+                pattern {
+                    type('EXCLUDE')
+                    pattern('.propsfile')
+                }
+                pattern {
+                    type('INCLUDE')
+                    pattern('.gitignore')
+                }
+            }
+        }
+    }
+}
+----
+
+== Configuration
+
+=== Patterns
+
+image::docs/images/ws-cleanup.png[]
+
+Files to be deleted are specified by pattern using https://ant.apache.org/manual/dirtasks.html[Ant pattern syntax].
+You can choose if the pattern is an _include_ pattern (if the file matches this pattern, the file will be removed) or _exclude_ pattern (if the file matches this pattern, the file won't be removed).
+If there is only an exclude pattern, `\**/*` (i.e., delete everything) will be used as the include pattern, which means that everything will be deleted except the files matching the exclude pattern.
+Patterns are applied only on files; if you want to apply them also on directories, check the appropriate box.
+
+WARNING: The directory is deleted with all its contents. If the directory matches the include pattern, everything in the directory will be deleted regardless as to whether some files in the directory match the exclude pattern.
+
+See the documentation for the Ant https://ant.apache.org/manual/api/org/apache/tools/ant/DirectoryScanner.html[`DirectoryScanner`] class for examples of patterns.
+
+=== Deferred wipeout
+
+When the whole workspace is supposed to be deleted (no patterns, external commands, etc.), the Workspace Cleanup plugin delegates to the https://plugins.jenkins.io/resource-disposer/[Resource Disposer] plugin to speed things up.
+
+When deferred wipeout is disabled, the old implementation of filesystem content deletion is used.
+If you want the same behavior as with deferred wipeout, you have to set the plugin attribute `deleteDirs` to true as well.
+For Pipeline jobs, you can do this as follows:
+
+[source,groovy]
+----
+cleanWs disableDeferredWipeout: true, deleteDirs: true
+----
+
+For e.g. cloud developers it might be useful to be sure deferred wipeout is never selected as a cleanup method.
+Therefore there is a new feature introduced to do this, implemented via a regular `NodeProperty` which you can attach to any node via the UI or via a Groovy script as follows:
+
+[source,java]
+----
+Node.getNodeProperties().add(new DisableDeferredWipeoutNodeProperty());
+----
+
+== Issues
+
+Report issues and enhancements in the https://issues.jenkins.io/[Jenkins issue tracker].
+Use the `ws-cleanup-plugin` component in the `JENKINS` project.
+
+== Contributing
+
+Refer to our https://github.com/jenkinsci/.github/blob/master/CONTRIBUTING.md[contribution guidelines].
+
+== License
+
+Licensed under link:LICENSE[the MIT License].