Add latest changes from gitlab-org/gitlab@master

1 files changed, 26 insertions, 19 deletions

diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md
index c85dd4555ca..9c977e4da40 100644
--- a/doc/user/project/repository/reducing_the_repo_size_using_git.md
+++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md
@@ -72,6 +72,12 @@ To purge files from a GitLab repository:
    cd project.git
    ```
 
+1. Because cloning from a bundle file sets the `origin` remote to the local bundle file, change it to the URL of your repository:
+
+   ```shell
+   git remote set-url origin https://gitlab.example.com/<namespace>/<project_name>.git
+   ```
+
 1. Using either `git filter-repo` or `git-sizer`, analyze your repository
    and review the results to determine which items you want to purge:
 
@@ -84,38 +90,39 @@ To purge files from a GitLab repository:
    git-sizer
    ```
 
-1. Proceed to purging any files from the history of your repository. Because we are
-   trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us
-   which internal refs to remove.
-
-   NOTE:
-   `git filter-repo` creates a new `commit-map` file every run, and overwrites the `commit-map` from
-   the previous run. You need this file from **every** run. Do the next step every time you run
-   `git filter-repo`.
+1. Purge the history of your repository using relevant `git filter-repo` options.
+   Two common options are:
 
-   To purge specific files, the `--path` and `--invert-paths` options can be combined:
+   - `--path` and `--invert-paths` to purge specific files:
 
-   ```shell
-   git filter-repo --path path/to/file.ext --invert-paths
-   ```
+     ```shell
+     git filter-repo --path path/to/file.ext --invert-paths
+     ```
 
-   To generally purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used:
+   - `--strip-blobs-bigger-than` to purge all files larger than for example 10M:
 
-   ```shell
-   git filter-repo --strip-blobs-bigger-than 10M
-   ```
+     ```shell
+     git filter-repo --strip-blobs-bigger-than 10M
+     ```
 
    See the
    [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES)
    for more examples and the complete documentation.
 
-1. Because cloning from a bundle file sets the `origin` remote to the local bundle file, delete this `origin` remote, and set it to the URL to your repository:
+1. Because you are trying to remove internal refs,
+   you'll later rely on `commit-map` files produced by each run
+   to tell you which internal refs to remove.
+   Every `git filter-repo` run creates a new `commit-map`,
+   and overwrites the `commit-map` from the previous run.
+   You can use the following command to back up each `commit-map` file:
 
    ```shell
-   git remote remove origin
-   git remote add origin https://gitlab.example.com/<namespace>/<project_name>.git
+   cp .git/filter-repo/commit-map ./_filter_repo_commit_map_$(date +%s)
    ```
 
+   Repeat this step and all following steps (including the [repository cleanup](#repository-cleanup) step)
+   every time you run any `git filter-repo` command.
+
 1. Force push your changes to overwrite all branches on GitLab:
 
    ```shell