From 3c72b4b7e39d8b342c084290c80d19d0e92343c5 Mon Sep 17 00:00:00 2001
From: Arseney300 <Arseney300@gmail.com>
Date: Fri, 20 Feb 2026 23:58:19 +0700
Subject: Document workspace persistence and cleanup methods

Explain incremental builds, Docker image caching vs container lifecycle,
and two ways to clean the workspace for Pipeline jobs (host deletion
and cleanWs plugin).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 doc/jenkins-cpp-build.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/doc/jenkins-cpp-build.md b/doc/jenkins-cpp-build.md
index 6449ffd..58212a3 100644
--- a/doc/jenkins-cpp-build.md
+++ b/doc/jenkins-cpp-build.md
@@ -285,6 +285,62 @@ This requires the **Git plugin** and **Poll SCM** to be enabled in the job
 config (the schedule can be empty, e.g. just `H * * * *`).
 
 
+## Incremental builds and cleaning the workspace
+
+After the first successful build, Jenkins keeps the workspace directory
+(`/var/jenkins_home/jobs/<job>/workspace/`) between builds. On subsequent
+runs it does a `git fetch` + `git checkout` instead of a full clone, only
+downloading new commits. This makes builds much faster, especially for
+large repositories like the Linux kernel.
+
+The same applies to Docker images: Jenkins pulls the image (e.g.,
+`kernel-builder` or `gcc:latest`) once and caches it locally. Future builds
+reuse the cached image. However, the Docker **container** is always created
+fresh for each build and destroyed when done — only the workspace persists.
+
+Sometimes you need a completely clean build (e.g., to rule out stale object
+files causing issues). Pipeline jobs do not have a "Wipe Out Workspace"
+button in the UI (only Freestyle jobs do). There are two ways to clean it:
+
+### Option A — Delete from host
+
+```bash
+rm -rf /var/jenkins_home/jobs/<job-name>/workspace
+```
+
+The next build will do a fresh clone.
+
+### Option B — Add cleanWs() to Jenkinsfile
+
+Requires the **Workspace Cleanup** plugin. Add a `post` block to
+automatically wipe the workspace after every build:
+
+```groovy
+pipeline {
+    agent {
+        docker { image 'gcc:latest' }
+    }
+
+    stages {
+        stage('Build') {
+            steps {
+                sh 'g++ -o my_app main.cpp'
+            }
+        }
+    }
+
+    post {
+        always {
+            cleanWs()
+        }
+    }
+}
+```
+
+Note: using `cleanWs()` means every build will do a full clone, which is
+slow for large repos. Use it only when you actually need clean builds.
+
+
 ## How DooD works
 
 Jenkins is configured with Docker-out-of-Docker: it mounts the host's
-- 
cgit v1.2.3