From 7b4186720c43b3e39bf93138c5ec076a0d6be3e2 Mon Sep 17 00:00:00 2001
From: Mattias Persson <mattiasbpersson@gmail.com>
Date: Thu, 22 Oct 2020 20:02:28 +0200
Subject: [PATCH] Clarify app.example.ini documentation (#13256)

* Clarify app.example.ini documentation

Hard to understand if cron i needed to activate all other cron.

* Added missing "Extended cron tasks" to config-cheat-sheet.en-us.md

cron default is false - setting it true activates all cron. Changed the documentation accordingly

* Fixed spelling

Co-authored-by: techknowlogick <techknowlogick@gitea.io>
---
 custom/conf/app.example.ini                        | 43 ++++++++---------
 .../doc/advanced/config-cheat-sheet.en-us.md       | 56 +++++++++++++++++++---
 2 files changed, 70 insertions(+), 29 deletions(-)

diff --git a/custom/conf/app.example.ini b/custom/conf/app.example.ini
index dc273ced80..a4e35d2495 100644
--- a/custom/conf/app.example.ini
+++ b/custom/conf/app.example.ini
@@ -915,12 +915,25 @@ PASSWD =
 RECEIVERS =
 
 [cron]
-; Enable running cron tasks periodically.
-ENABLED = true
+; Enable running all cron tasks periodically with default settings.
+ENABLED = false
 ; Run cron tasks when Gitea starts.
 RUN_AT_START = false
 
-; Basic cron tasks
+; Basic cron tasks - enabled by default
+
+; Clean up old repository archives
+[cron.archive_cleanup]
+; Whether to enable the job
+ENABLED = true
+; Whether to always run at least once at start up time (if ENABLED)
+RUN_AT_START = true
+; Notice if not success
+NO_SUCCESS_NOTICE = false
+; Time interval for job to run
+SCHEDULE = @every 24h
+; Archives created more than OLDER_THAN ago are subject to deletion
+OLDER_THAN = 24h
 
 ; Update mirrors
 [cron.update_mirrors]
@@ -956,18 +969,15 @@ RUN_AT_START = true
 NO_SUCCESS_NOTICE = false
 SCHEDULE = @every 24h
 
-; Clean up old repository archives
-[cron.archive_cleanup]
-; Whether to enable the job
+[cron.update_migration_poster_id]
+; Update migrated repositories' issues and comments' posterid, it will always attempt synchronization when the instance starts.
 ENABLED = true
-; Whether to always run at least once at start up time (if ENABLED)
+; Update migrated repositories' issues and comments' posterid when starting server (default true)
 RUN_AT_START = true
 ; Notice if not success
 NO_SUCCESS_NOTICE = false
-; Time interval for job to run
+; Interval as a duration between each synchronization. (default every 24h)
 SCHEDULE = @every 24h
-; Archives created more than OLDER_THAN ago are subject to deletion
-OLDER_THAN = 24h
 
 ; Synchronize external user data (only LDAP user synchronization is supported)
 [cron.sync_external_users]
@@ -994,18 +1004,7 @@ SCHEDULE = @every 24h
 ; deleted branches than OLDER_THAN ago are subject to deletion
 OLDER_THAN = 24h
 
-[cron.update_migration_poster_id]
-; Update migrated repositories' issues and comments' posterid, it will always attempt synchronization when the instance starts.
-ENABLED = true
-; Update migrated repositories' issues and comments' posterid when starting server (default true)
-RUN_AT_START = true
-; Notice if not success
-NO_SUCCESS_NOTICE = false
-; Interval as a duration between each synchronization. (default every 24h)
-SCHEDULE = @every 24h
-
-; Extened cron task
-; they was not enabled as default
+; Extended cron task - not enabled by default
 
 ; Delete all unactivated accounts
 [cron.delete_inactive_accounts]
diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md
index b2e56ec4ae..ed2254f247 100644
--- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md
+++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md
@@ -668,42 +668,84 @@ NB: You must `REDIRECT_MACARON_LOG` and have `DISABLE_ROUTER_LOG` set to `false`
 
 ## Cron (`cron`)
 
-- `ENABLED`: **true**: Run cron tasks periodically.
+- `ENABLED`: **false**: Enable to run all cron tasks periodically with default settings.
 - `RUN_AT_START`: **false**: Run cron tasks at application start-up.
 - `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 
-### Cron - Cleanup old repository archives (`cron.archive_cleanup`)
+### Basic cron tasks - enabled by default
+
+#### Cron - Cleanup old repository archives (`cron.archive_cleanup`)
 
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
 - `SCHEDULE`: **@every 24h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
 - `OLDER_THAN`: **24h**: Archives created more than `OLDER_THAN` ago are subject to deletion, e.g. `12h`.
 
-### Cron - Update Mirrors (`cron.update_mirrors`)
+#### Cron - Update Mirrors (`cron.update_mirrors`)
 
 - `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
 - `NO_SUCCESS_NOTICE`: **true**: The cron task for update mirrors success report is not very useful - as it just means that the mirrors have been queued. Therefore this is turned off by default.
 
-### Cron - Repository Health Check (`cron.repo_health_check`)
+#### Cron - Repository Health Check (`cron.repo_health_check`)
 
 - `SCHEDULE`: **@every 24h**: Cron syntax for scheduling repository health check.
 - `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
 - `ARGS`: **\<empty\>**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
 
-### Cron - Repository Statistics Check (`cron.check_repo_stats`)
+#### Cron - Repository Statistics Check (`cron.check_repo_stats`)
 
 - `RUN_AT_START`: **true**: Run repository statistics check at start time.
 - `SCHEDULE`: **@every 24h**: Cron syntax for scheduling repository statistics check.
 
-### Cron - Update Migration Poster ID (`cron.update_migration_poster_id`)
+#### Cron - Update Migration Poster ID (`cron.update_migration_poster_id`)
 
 - `SCHEDULE`: **@every 24h** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 
-### Cron - Sync External Users (`cron.sync_external_users`)
+#### Cron - Sync External Users (`cron.sync_external_users`)
 
 - `SCHEDULE`: **@every 24h** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 - `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
 
+### Extended cron tasks (not enabled by default)
+
+#### Cron - Garbage collect all repositories ('cron.git_gc_repos')
+- `ENABLED`: **false**: Enable service.
+- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+- `TIMEOUT`: **60s**: Time duration syntax for garbage collection execution timeout.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `ARGS`: **\<empty\>**: Arguments for command `git gc`, e.g. `--aggressive --auto`. The default value is same with [git] -> GC_ARGS
+
+#### Cron - Update the '.ssh/authorized_keys' file with Gitea SSH keys ('cron.resync_all_sshkeys')
+- `ENABLED`: **false**: Enable service.
+- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+
+#### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories ('cron.resync_all_hooks')
+- `ENABLED`: **false**: Enable service.
+- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+
+#### Cron - Reinitialize all missing Git repositories for which records exist ('cron.reinit_missing_repos')
+- `ENABLED`: **false**: Enable service.
+- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+
+#### Cron - Delete all repositories missing their Git files ('cron.delete_missing_repos')
+- `ENABLED`: **false**: Enable service.
+- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+
+#### Cron -  Delete generated repository avatars ('cron.delete_generated_repository_avatars')
+- `ENABLED`: **false**: Enable service.
+- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+
 ## Git (`git`)
 
 - `PATH`: **""**: The path of git executable. If empty, Gitea searches through the PATH environment.