From 81ebaeca4185e2e44e589d6cb3e88cbfc7e0895c Mon Sep 17 00:00:00 2001
From: Sam Gleske <875669+samrocketman@users.noreply.github.com>
Date: Wed, 11 Mar 2020 09:03:44 -0400
Subject: [PATCH] Improved JENKINS_HOME example (#3332)

After years of use I've come up with some improvements to the
`JENKINS_HOME.gitignore` example.

- Major performance improvement: On very large Jenkins installations that
  have been running for more than one year, there tends to be many builds
  (hundreds of thousands of builds).  The `builds` directory of these
  jobs contain millions of files which would cause Git to hang for
  several minutes on simple commands like `git status` and longer for
  committing changes.  `strace` was used on Git to figure out the
  performance impact and this proposed change includes the optimization.
  I also added a clear comment explaining the line's purpose.
- There's an example for how to include Jenkins encryption keys, and
  there's a disclaimer informing the user why they shouldn't but still
  giving an example.
- Comments have been reworded and slightly reformatted to be a little
  more clear.
---
 JENKINS_HOME.gitignore | 41 +++++++++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/JENKINS_HOME.gitignore b/JENKINS_HOME.gitignore
index 6df01d62..2516c099 100644
--- a/JENKINS_HOME.gitignore
+++ b/JENKINS_HOME.gitignore
@@ -1,25 +1,50 @@
-#Learn more about Jenkins and JENKINS_HOME directory for which this file is intended.
+# Learn more about Jenkins and JENKINS_HOME directory for which this file is
+# intended.
+#
 #  http://jenkins-ci.org/
 #  https://wiki.jenkins-ci.org/display/JENKINS/Administering+Jenkins
+#
+# Note: secret.key is purposefully not tracked by git. This should be backed up
+# separately because configs may contain secrets which were encrypted using the
+# secret.key.  To back up secrets use 'tar -czf /tmp/secrets.tgz secret*' and
+# save the file separate from your repository.  If you want secrets backed up
+# with configuration, then see the bottom of this file for an example.
 
-#ignore all JENKINS_HOME except jobs directory, root xml config, and .gitignore file
+# Ignore all JENKINS_HOME except jobs directory, root xml config, and
+# .gitignore file.
 /*
 !/jobs
 !/.gitignore
 !/*.xml
 
-#ignore all files in jobs subdirectories except for folders
-#note: git doesn't track folders, only file content
+# Ignore all files in jobs subdirectories except for folders.
+# Note: git doesn't track folders, only file content.
 jobs/**
 !jobs/**/
 
-#uncomment the following line to save next build numbers with config
+# Uncomment the following line to save next build numbers with config.
+
 #!jobs/**/nextBuildNumber
 
-#exclude only config.xml files in repository subdirectories
+# For performance reasons, we want to ignore builds in Jenkins jobs because it
+# contains many tiny files on large installations.  This can impact git
+# performance when running even basic commands like 'git status'.
+builds
+indexing
+
+# Exclude only config.xml files in repository subdirectories.
 !config.xml
 
-#don't track workspaces (when users build on the master)
+# Don't track workspaces (when users build on the master).
 jobs/**/*workspace
 
-#as a result only settings and job config.xml files in JENKINS_HOME will be tracked by git
+# Security warning: If secrets are included with your configuration, then an
+# adversary will be able to decrypt all encrypted secrets within Jenkins
+# config.  Including secrets is a bad practice, but the example is included in
+# case someone still wants it for convenience.  Uncomment the following line to
+# include secrets for decryption with repository configuration in Git.
+
+#!/secret*
+
+# As a result, only Jenkins settings and job config.xml files in JENKINS_HOME
+# will be tracked by git.