Improve repository maintenance UI and documentation

Changelog: other

app/views/admin/application_settings/_repository_check.html.haml

@@ -8,15 +8,16 @@
         .form-check
           = f.check_box :repository_checks_enabled, class: 'form-check-input'
           = f.label :repository_checks_enabled, class: 'form-check-label' do
-            = _("Enable Repository Checks")
+            = _("Enable repository checks")
           .form-text.text-muted
-            - link_to_git_fsck = link_to('git fsck', 'https://git-scm.com/docs/git-fsck', target: '_blank')
-            = _("GitLab will periodically run %{link_to_git_fsck} in all project and wiki repositories to look for silent disk corruption issues.").html_safe % { link_to_git_fsck: link_to_git_fsck }
+            = _("Run")
+            %code= _("git fsck")
+            = _("periodically in all project and wiki repositories to look for silent disk corruption issues.")
       .form-group
         .form-text.text-muted
-          = _("If you got a lot of false alarms from repository checks you can choose to clear all repository check information from the database.")
+          = _("If you get a lot of false alarms from repository checks, you can clear all repository check information from the database.")
           - clear_repository_checks_link = _('Clear all repository checks')
-          - clear_repository_checks_message = _('This will clear repository check states for ALL projects in the database. This cannot be undone. Are you sure?')
+          - clear_repository_checks_message = _('This clears repository check states for all projects in the database and cannot be undone. Are you sure?')
         = link_to clear_repository_checks_link, clear_repository_check_states_admin_application_settings_path, data: { confirm: clear_repository_checks_message }, method: :put, class: "gl-button btn btn-sm btn-danger gl-mt-3"
 
     .sub-section
@@ -25,29 +26,37 @@
         .form-check
           = f.check_box :housekeeping_enabled, class: 'form-check-input'
           = f.label :housekeeping_enabled, class: 'form-check-label' do
-            = _("Enable automatic repository housekeeping (git repack, git gc)")
+            = _("Enable automatic repository housekeeping")
           .form-text.text-muted
-            = _("If you keep automatic housekeeping disabled for a long time Git repository access on your GitLab server will become slower and your repositories will use more disk space. We recommend to always leave this enabled.")
+            = _("Leaving this setting enabled is recommended.")
+            = link_to s_('Learn more.'), help_page_path('administration/housekeeping.md', anchor: 'housekeeping-options'), target: '_blank', rel: 'noopener noreferrer'
         .form-check
           = f.check_box :housekeeping_bitmaps_enabled, class: 'form-check-input'
           = f.label :housekeeping_bitmaps_enabled, class: 'form-check-label' do
             = _("Enable Git pack file bitmap creation")
           .form-text.text-muted
-            = _("Creating pack file bitmaps makes housekeeping take a little longer but bitmaps should accelerate 'git clone' performance.")
+            = _("Improves Git cloning performance.")
+            = link_to s_('Learn more.'), help_page_path('administration/housekeeping.md', anchor: 'housekeeping-options'), target: '_blank', rel: 'noopener noreferrer'
       .form-group
         = f.label :housekeeping_incremental_repack_period, 'Incremental repack period', class: 'label-bold'
         = f.number_field :housekeeping_incremental_repack_period, class: 'form-control gl-form-input'
         .form-text.text-muted
-          = _("Number of Git pushes after which an incremental 'git repack' is run.")
+          = _("Number of Git pushes after which an incremental")
+          %code= _("git repack")
+          = _("is run.")
       .form-group
         = f.label :housekeeping_full_repack_period, 'Full repack period', class: 'label-bold'
         = f.number_field :housekeeping_full_repack_period, class: 'form-control gl-form-input'
         .form-text.text-muted
-          = _("Number of Git pushes after which a full 'git repack' is run.")
+          = _("Number of Git pushes after which a full")
+          %code= _("git repack")
+          = _("is run.")
       .form-group
         = f.label :housekeeping_gc_period, _('Git GC period'), class: 'label-bold'
         = f.number_field :housekeeping_gc_period, class: 'form-control gl-form-input'
         .form-text.text-muted
-          = _("Number of Git pushes after which 'git gc' is run.")
+          = _("Number of Git pushes after which")
+          %code= _("git gc")
+          = _("is run.")
 
   = f.submit _('Save changes'), class: "gl-button btn btn-confirm"

app/views/admin/application_settings/repository.html.haml

@@ -42,7 +42,11 @@
     %button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
       = expanded_by_default? ? _('Collapse') : _('Expand')
     %p
-      = _('Configure automatic git checks and housekeeping on repositories.')
+      = _('Configure')
+      = link_to s_('repository checks'), help_page_path('administration/repository_checks.md'), target: '_blank', rel: 'noopener noreferrer'
+      = _('and')
+      = link_to s_('housekeeping'), help_page_path('administration/housekeeping.md'), target: '_blank', rel: 'noopener noreferrer'
+      = _('on repositories.')
   .settings-content
     = render 'repository_check'
 

doc/administration/housekeeping.md

@@ -4,46 +4,68 @@ group: Distribution
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Housekeeping **(FREE)**
+# Housekeeping **(FREE SELF)**
 
-GitLab supports and automates housekeeping tasks within your current repository,
-such as compressing file revisions and removing unreachable objects.
+GitLab supports and automates housekeeping tasks within your current repository such as:
+
+- Compressing Git objects.
+- Removing unreachable objects.
 
 ## Configure housekeeping
 
-GitLab automatically runs `git gc` and `git repack` on repositories
-after Git pushes.
+GitLab automatically runs `git gc` and `git repack` on repositories after Git pushes:
+
+- [`git gc`](https://git-scm.com/docs/git-gc) runs a number of housekeeping tasks such as:
+  - Compressing Git objects to reduce disk space and increase performance.
+  - Removing unreachable objects that may have been created from changes to the repository, like force-overwriting branches.
+- [`git repack`](https://git-scm.com/docs/git-repack) either:
+  - Runs an incremental repack, according to a [configured period](#housekeeping-options). This
+    packs all loose objects into a new packfile and prunes the now-redundant loose objects.
+  - Runs a full repack, according to a [configured period](#housekeeping-options). This repacks all
+    packfiles and loose objects into a single new packfile, and deletes the old now-redundant loose
+    objects and packfiles. It also optionally creates bitmaps for the new packfile.
 
 You can change how often this happens or turn it off:
 
 1. On the top bar, select **Menu >** **{admin}** **Admin**.
 1. On the left sidebar, select **Settings > Repository**.
 1. Expand **Repository maintenance**.
-1. Configure the Housekeeping options.
+1. In the **Housekeeping** section, configure the [housekeeping options](#housekeeping-options).
 1. Select **Save changes**.
 
-For example, in the following scenario a `git repack -d` will be executed:
+### Housekeeping options
+
+The following housekeeping options are available:
+
+- **Enable automatic repository housekeeping**: Regularly run `git repack` and `git gc`. If you
+  keep this setting disabled for a long time, Git repository access on your GitLab server becomes
+  slower and your repositories use more disk space.
+- **Enable Git pack file bitmap creation**: Create pack file bitmaps which accelerates `git clone`
+  performance. Makes housekeeping take a little longer.
+- **Incremental repack period**: Number of Git pushes after which an incremental `git repack` is
+  run.
+- **Full repack period**: Number of Git pushes after which a full `git repack` is run.
+- **Git GC period**: Number of Git pushes after which `git gc` is run.
+
+As an example, see the following scenario:
 
-- Project: pushes since GC counter (`pushes_since_gc`) = `10`
-- Git GC period = `200`
-- Full repack period = `50`
+- Incremental repack period: 10.
+- Full repack period: 50.
+- Git GC period: 200.
 
-When the `pushes_since_gc` value is 50 a `repack -A -d --pack-kept-objects` runs, similarly when
-the `pushes_since_gc` value is 200 a `git gc` runs:
+When the:
 
-- `git gc` ([man page](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-gc.html)) runs a number of housekeeping tasks,
-  such as compressing file revisions (to reduce disk space and increase performance)
-  and removing unreachable objects which may have been created from prior invocations of
-  `git add`.
-- `git repack` ([man page](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-repack.html)) re-organize existing packs into a single, more efficient pack.
+- `pushes_since_gc` value is 50, a `repack -A -l -d --pack-kept-objects` runs.
+- `pushes_since_gc` value is 200, a `git gc` runs.
 
 Housekeeping also [removes unreferenced LFS files](../raketasks/cleanup.md#remove-unreferenced-lfs-files)
-from your project on the same schedule as the `git gc` operation, freeing up storage space for your project.
+from your project on the same schedule as the `git gc` operation, freeing up storage space for your
+project.
 
 ## How housekeeping handles pool repositories
 
-Housekeeping for pool repositories is handled differently from standard repositories.
-It is ultimately performed by the Gitaly RPC `FetchIntoObjectPool`.
+Housekeeping for pool repositories is handled differently from standard repositories. It is
+ultimately performed by the Gitaly RPC `FetchIntoObjectPool`.
 
 This is the current call stack by which it is invoked:
 
@@ -54,10 +76,10 @@ This is the current call stack by which it is invoked:
 1. `ObjectPoolService#fetch`
 1. `Gitaly::FetchIntoObjectPoolRequest`
 
-To manually invoke it from a Rails console, if needed, you can call `project.pool_repository.object_pool.fetch`.
-This is a potentially long-running task, though Gitaly times out in about 8 hours.
+To manually invoke it from a Rails console if needed, you can call
+`project.pool_repository.object_pool.fetch`. This is a potentially long-running task, though Gitaly
+times out in about 8 hours.
 
 WARNING:
-Do not run `git prune` or `git gc` in pool repositories! This can
-cause data loss in "real" repositories that depend on the pool in
-question.
+Do not run `git prune` or `git gc` in pool repositories! This can cause data loss in "real"
+repositories that depend on the pool in question.

doc/administration/repository_checks.md

@@ -5,57 +5,64 @@ info: "To determine the technical writer assigned to the Stage/Group associated
 type: reference
 ---
 
-# Repository checks **(FREE)**
+# Repository checks **(FREE SELF)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3232) in GitLab 8.7.
+You can use [`git fsck`](https://git-scm.com/docs/git-fsck) to verify the integrity of all data
+committed to a repository. GitLab administrators can trigger this check for a project using the
+GitLab UI:
 
-Git has a built-in mechanism, [`git fsck`](https://git-scm.com/docs/git-fsck), to verify the
-integrity of all data committed to a repository. GitLab administrators
-can trigger such a check for a project via the project page under the
-Admin Area. The checks run asynchronously so it may take a few minutes
-before the check result is visible on the project Admin Area. If the
-checks failed you can see their output on in the
-[`repocheck.log` file.](logs.md#repochecklog)
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Overview > Projects**.
+1. Select the project to check.
+1. In the **Repository check** section, select **Trigger repository check**.
+
+The checks run asynchronously so it may take a few minutes before the check result is visible on the
+project page in the Admin Area. If the checks fail, see [what to do](#what-to-do-if-a-check-failed).
 
 This setting is off by default, because it can cause many false alarms.
 
-## Periodic checks
+## Enable periodic checks
+
+Instead of checking repositories manually, GitLab can be configured to run the checks periodically:
+
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`).
+1. Expand the **Repository maintenance** section.
+1. Enable **Enable repository checks**.
 
-When enabled, GitLab periodically runs a repository check on all project
-repositories and wiki repositories in order to detect data corruption.
-A project is checked no more than once per month. If any projects
-fail their repository checks all GitLab administrators receive an email
-notification of the situation. This notification is sent out once a week,
-by default, midnight at the start of Sunday. Repositories with known check
-failures can be found at `/admin/projects?last_repository_check_failed=1`.
+When enabled, GitLab periodically runs a repository check on all project repositories and wiki
+repositories to detect possible data corruption. A project is checked no more than once per month.
 
-## Disabling periodic checks
+If any projects fail their repository checks, all GitLab administrators receive an email
+notification of the situation. By default, this notification is sent out once a week at midnight at
+the start of Sunday.
 
-You can disable the periodic checks on the **Settings** page of the Admin Area.
+Repositories with known check failures can be found at
+`/admin/projects?last_repository_check_failed=1`.
 
 ## What to do if a check failed
 
-If the repository check fails for some repository you should look up the error
-in the [`repocheck.log` file](logs.md#repochecklog) on disk:
+If a repository check fails, locate the error in the [`repocheck.log` file](logs.md#repochecklog) on
+disk at:
 
-- `/var/log/gitlab/gitlab-rails` for Omnibus GitLab installations
-- `/home/git/gitlab/log` for installations from source
+- `/var/log/gitlab/gitlab-rails` for Omnibus GitLab installations.
+- `/home/git/gitlab/log` for installations from source.
 
-If the periodic repository check causes false alarms, you can clear all repository check states by:
+If periodic repository checks cause false alarms, you can clear all repository check states:
 
 1. On the top bar, select **Menu >** **{admin}** **Admin**.
 1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`).
 1. Expand the **Repository maintenance** section.
 1. Select **Clear all repository checks**.
 
-## Run a check manually
+## Run a check using the command line
 
-[`git fsck`](https://git-scm.com/docs/git-fsck) is a read-only check that you can run
-manually against the repository on the [Gitaly server](gitaly/index.md).
+You can run [`git fsck`](https://git-scm.com/docs/git-fsck) using the command line on repositories
+on [Gitaly servers](gitaly/index.md). To locate the repositories:
 
-- For Omnibus GitLab installations, repositories are stored by default in
-  `/var/opt/gitlab/git-data/repositories`.
-- [Identify the subdirectory that contains the repository](repository_storage_types.md#from-project-name-to-hashed-path)
+1. Go to the storage location for repositories. For Omnibus GitLab installations, repositories are
+   stored by default in the `/var/opt/gitlab/git-data/repositories` directory.
+1. [Identify the subdirectory that contains the repository](repository_storage_types.md#from-project-name-to-hashed-path)
    that you need to check.
 
 To run a check (for example):
@@ -65,5 +72,5 @@ sudo /opt/gitlab/embedded/bin/git -C /var/opt/gitlab/git-data/repositories/@hash
 ```
 
 You can also run [Rake tasks](raketasks/check.md#repository-integrity) for checking Git
-repositories, which can be used to run `git fsck` against all repositories and generate
-repository checksums, as a way to compare repositories on different servers.
+repositories, which can be used to run `git fsck` against all repositories and generate repository
+checksums, as a way to compare repositories on different servers.

locale/gitlab.pot

@@ -8196,6 +8196,9 @@ msgstr ""
 msgid "Configuration help"
 msgstr ""
 
+msgid "Configure"
+msgstr ""
+
 msgid "Configure %{link} to track events. %{link_start}Learn more.%{link_end}"
 msgstr ""
 
@@ -8235,9 +8238,6 @@ msgstr ""
 msgid "Configure a %{codeStart}.gitlab-webide.yml%{codeEnd} file in the %{codeStart}.gitlab%{codeEnd} directory to start using the Web Terminal. %{helpStart}Learn more.%{helpEnd}"
 msgstr ""
 
-msgid "Configure automatic git checks and housekeeping on repositories."
-msgstr ""
-
 msgid "Configure existing installation"
 msgstr ""
 
@@ -9495,9 +9495,6 @@ msgstr ""
 msgid "Creating graphs uses the data from the Prometheus server. If this takes a long time, ensure that data is available."
 msgstr ""
 
-msgid "Creating pack file bitmaps makes housekeeping take a little longer but bitmaps should accelerate 'git clone' performance."
-msgstr ""
-
 msgid "Creation date"
 msgstr ""
 
@@ -12043,9 +12040,6 @@ msgstr ""
 msgid "Enable Registration Features"
 msgstr ""
 
-msgid "Enable Repository Checks"
-msgstr ""
-
 msgid "Enable SSL verification"
 msgstr ""
 
@@ -12088,7 +12082,7 @@ msgstr ""
 msgid "Enable authentication"
 msgstr ""
 
-msgid "Enable automatic repository housekeeping (git repack, git gc)"
+msgid "Enable automatic repository housekeeping"
 msgstr ""
 
 msgid "Enable classification control using an external service"
@@ -12151,6 +12145,9 @@ msgstr ""
 msgid "Enable reCAPTCHA, Invisible Captcha, Akismet and set IP limits. For reCAPTCHA, we currently only support %{recaptcha_v2_link_start}v2%{recaptcha_v2_link_end}"
 msgstr ""
 
+msgid "Enable repository checks"
+msgstr ""
+
 msgid "Enable service ping"
 msgstr ""
 
@@ -14962,9 +14959,6 @@ msgstr ""
 msgid "GitLab will inform you if a new version is available."
 msgstr ""
 
-msgid "GitLab will periodically run %{link_to_git_fsck} in all project and wiki repositories to look for silent disk corruption issues."
-msgstr ""
-
 msgid "GitLab will run a background job that will produce pseudonymized CSVs of the GitLab database that will be uploaded to your configured object storage directory."
 msgstr ""
 
@@ -16448,10 +16442,7 @@ msgstr ""
 msgid "If you did not recently sign in, you should immediately change your password: %{password_link}."
 msgstr ""
 
-msgid "If you got a lot of false alarms from repository checks you can choose to clear all repository check information from the database."
-msgstr ""
-
-msgid "If you keep automatic housekeeping disabled for a long time Git repository access on your GitLab server will become slower and your repositories will use more disk space. We recommend to always leave this enabled."
+msgid "If you get a lot of false alarms from repository checks, you can clear all repository check information from the database."
 msgstr ""
 
 msgid "If you lose your recovery codes you can generate new ones, invalidating all previous codes."
@@ -16685,6 +16676,9 @@ msgstr ""
 msgid "Improve search with Advanced Search and GitLab Enterprise Edition."
 msgstr ""
 
+msgid "Improves Git cloning performance."
+msgstr ""
+
 msgid "In %{time_to_now}"
 msgstr ""
 
@@ -19338,6 +19332,9 @@ msgstr ""
 msgid "Leave zen mode"
 msgstr ""
 
+msgid "Leaving this setting enabled is recommended."
+msgstr ""
+
 msgid "Legacy burndown chart"
 msgstr ""
 
@@ -22545,13 +22542,13 @@ msgstr ""
 msgid "Number of Elasticsearch shards and replicas (per index)"
 msgstr ""
 
-msgid "Number of Git pushes after which 'git gc' is run."
+msgid "Number of Git pushes after which"
 msgstr ""
 
-msgid "Number of Git pushes after which a full 'git repack' is run."
+msgid "Number of Git pushes after which a full"
 msgstr ""
 
-msgid "Number of Git pushes after which an incremental 'git repack' is run."
+msgid "Number of Git pushes after which an incremental"
 msgstr ""
 
 msgid "Number of LOCs per commit"
@@ -28045,6 +28042,9 @@ msgstr ""
 msgid "Rules that define what git pushes are accepted for a project. All newly created projects will use these settings."
 msgstr ""
 
+msgid "Run"
+msgstr ""
+
 msgid "Run CI/CD pipelines for external repositories"
 msgstr ""
 
@@ -33162,6 +33162,9 @@ msgstr ""
 msgid "This chart could not be displayed"
 msgstr ""
 
+msgid "This clears repository check states for all projects in the database and cannot be undone. Are you sure?"
+msgstr ""
+
 msgid "This code snippet contains everything reflected in the configuration form. Copy and paste it into %{linkStart}.gitlab-ci.yml%{linkEnd} file and save your changes. Future %{scanType} scans will use these settings."
 msgstr ""
 
@@ -33588,9 +33591,6 @@ msgstr ""
 msgid "This variable can not be masked."
 msgstr ""
 
-msgid "This will clear repository check states for ALL projects in the database. This cannot be undone. Are you sure?"
-msgstr ""
-
 msgid "This will redirect you to an external sign in page."
 msgstr ""
 
@@ -38609,6 +38609,15 @@ msgid_plural "from %d jobs"
 msgstr[0] ""
 msgstr[1] ""
 
+msgid "git fsck"
+msgstr ""
+
+msgid "git gc"
+msgstr ""
+
+msgid "git repack"
+msgstr ""
+
 msgid "group"
 msgstr ""
 
@@ -38642,6 +38651,9 @@ msgstr ""
 msgid "here"
 msgstr ""
 
+msgid "housekeeping"
+msgstr ""
+
 msgid "http:"
 msgstr ""
 
@@ -38737,6 +38749,9 @@ msgstr ""
 msgid "is read-only"
 msgstr ""
 
+msgid "is run."
+msgstr ""
+
 msgid "is too long (%{current_value}). The maximum size is %{max_size}."
 msgstr ""
 
@@ -39237,6 +39252,9 @@ msgstr ""
 msgid "nounSeries|%{item}, and %{lastItem}"
 msgstr ""
 
+msgid "on repositories."
+msgstr ""
+
 msgid "on track"
 msgstr ""
 
@@ -39280,6 +39298,9 @@ msgstr ""
 msgid "per day"
 msgstr ""
 
+msgid "periodically in all project and wiki repositories to look for silent disk corruption issues."
+msgstr ""
+
 msgid "personal access token"
 msgstr ""
 
@@ -39385,6 +39406,9 @@ msgid_plural "replies"
 msgstr[0] ""
 msgstr[1] ""
 
+msgid "repository checks"
+msgstr ""
+
 msgid "repository:"
 msgstr ""