Merge branch 'docs-new-topic-user-project-repo-index' into 'master'

Docs new topic "user/project/repository/index.md"

Closes #27653 and #28665

See merge request !12598

8 files changed, 240 insertions, 6 deletions

diff --git a/doc/README.md b/doc/README.md
index 5537f54ab2b..a2864543b39 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -56,7 +56,7 @@ Shortcuts to GitLab's most visited docs:
 
 ### Repository
 
-Manage files and branches from the UI (user interface):
+Manage your [repositories](user/project/repository/index.md) from the UI (user interface):
 
 - Files
   - [Create a file](user/project/repository/web_editor.md#create-a-file)
diff --git a/doc/user/index.md b/doc/user/index.md
index f545dbffde3..8e43c8d6e3b 100644
--- a/doc/user/index.md
+++ b/doc/user/index.md
@@ -71,6 +71,11 @@ your code, use it as an issue tracker, collaborate on code, and continuously
 build, test, and deploy your app with built-in GitLab CI/CD. Or, you can do
 it all at once, from one single project.
 
+### Repository
+
+Host your codebase in [GitLab repositories](project/repository/index.md) with version control
+and as part of a fully integrated platform.
+
 ### Issues
 
 Explore the best of GitLab [Issues](project/issues/index.md).
diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md
index 138276edf07..074b2c19c43 100644
--- a/doc/user/project/issues/issues_functionalities.md
+++ b/doc/user/project/issues/issues_functionalities.md
@@ -58,17 +58,15 @@ Learn more on the [Multiple Assignees documentation](https://docs.gitlab.com/ee/
 
 - Select a [milestone](../milestones/index.md) to attribute that issue to.
 
-#### 5. Time Tracking (EES/EEP)
-
-This feature is available only in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/).
+#### 5. Time Tracking
 
 - Estimate time: add an estimate time in which the issue will be implemented
 - Spend: add the time spent on the implementation of that issue
 
 > **Note:**
-both estimate and spend times are set via [GitLab Quick Actions](../quick_actions.md).
+Both estimate and spend times are set via [GitLab Quick Actions](../quick_actions.md).
 
-Learn more on the [Time Tracking documentation](https://docs.gitlab.com/ee/workflow/time_tracking.html).
+Learn more on the [Time Tracking documentation](../../../workflow/time_tracking.md).
 
 #### 6. Due date
 
diff --git a/doc/user/project/repository/img/compare_branches.png b/doc/user/project/repository/img/compare_branches.png
new file mode 100755
index 00000000000..353bd72ef4e
--- /dev/null
+++ b/doc/user/project/repository/img/compare_branches.png
diff --git a/doc/user/project/repository/img/contributors_graph.png b/doc/user/project/repository/img/contributors_graph.png
new file mode 100755
index 00000000000..c31da7aa1ff
--- /dev/null
+++ b/doc/user/project/repository/img/contributors_graph.png
diff --git a/doc/user/project/repository/img/repo_graph.png b/doc/user/project/repository/img/repo_graph.png
new file mode 100755
index 00000000000..28da8ad9589
--- /dev/null
+++ b/doc/user/project/repository/img/repo_graph.png
diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md
new file mode 100644
index 00000000000..bb41eb41795
--- /dev/null
+++ b/doc/user/project/repository/index.md
@@ -0,0 +1,150 @@
+# Repository
+
+A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)
+is what you use to store your codebase in GitLab and change it with version control.
+A repository is part of a project, which has a lot of other features.
+
+## Create a repository
+
+To create a new repository, all you need to do is
+[create a new project](../../../gitlab-basics/create-project.md).
+
+Once you create a new project, you can add new files via UI
+(read the section below) or via command line.
+To add files from the command line, follow the instructions that will
+be presented on the screen when you create a new project, or read
+through them in the [command line basics](../../../gitlab-basics/start-using-git.md)
+documentation.
+
+> **Important:**
+For security reasons, when using the command line, we strongly recommend
+you to [connect with GitLab via SSH](../../../ssh/README.md).
+
+## Create and edit files
+
+Host your codebase in GitLab repositories by pushing your files to GitLab.
+You can either use the user interface (UI), or connect your local computer
+with GitLab [through the command line](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project).
+
+To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy
+you code, add a file called [.`gitlab-ci.yml`](../../../ci/quick_start/README.md)
+to your repository's root.
+
+**From the user interface:**
+
+GitLab's UI allows you to perform lots of Git commands without having to
+touch the command line. Even if you use the command line regularly, sometimes
+it's easier to do so [via GitLab UI](web_editor.md):
+
+- [Create a file](web_editor.md#create-a-file)
+- [Upload a file](web_editor.md#upload-a-file)
+- [File templates](web_editor.md#template-dropdowns)
+- [Create a directory](web_editor.md#create-a-directory)
+- [Start a merge request](web_editor.md#tips)
+
+**From the command line:**
+
+To get started with the command line, please read through the
+[command line basics documentation](../../../gitlab-basics/command-line-commands.md).
+
+## Branches
+
+When you submit changes in a new branch, you create a new version
+of that project's file tree. Your branch contains all the changes
+you are presenting, which are detected by Git line by line.
+
+To continue your workflow, once you pushed your changes to a new branch,
+you can create a [merge request](../merge_requests/index.md), perform
+inline code review, and [discuss](../../discussions/index.md)
+your implementation with your team.
+You can live preview changes submitted to a new branch with
+[Review Apps](../../../ci/review_apps/index.md).
+
+With [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/)
+subscriptions, you can also request
+[approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html#merge-request-approvals) from your managers.
+
+To create, delete, and branches via GitLab's UI:
+
+- [Create a branch](web_editor.md#create-a-new-branch)
+- [Protected branches](../protected_branches.md#protected-branches)
+- [Delete merged branches](branches/index.md#delete-merged-branches)
+
+Alternatively, you can use the
+[command line](../../../gitlab-basics/start-using-git.md#create-a-branch).
+
+To learn more about branching strategies read through the
+[GitLab Flow](../../../university/training/gitlab_flow.md) documentation.
+
+## Commits
+
+When you [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository),
+you are introducing those changes to your branch.
+Via command line, you can commit multiple times before pushing.
+
+- **Commit message:**
+A commit message is important to identity what is being changed and,
+more importantly, why. In GitLab, you can add keywords to the commit
+message that will perform one of the actions below:
+  - **Trigger a GitLab CI/CD pipeline:**
+  If you have your project configured with [GitLab CI/CD](../../../ci/README.md),
+  you will trigger a pipeline per push, not per commit.
+  - **Skip pipelines:**
+  You can add to you commit message the keyword
+  [`[ci skip]`](../../../ci/yaml/README.html#skipping-jobs)
+  and GitLab CI will skip that pipeline.
+  - **Cross-link issues and merge requests:**
+  [Cross-linking](../issues/crosslinking_issues.md#from-commit-messages)
+  is great to keep track of what's is somehow related in your workflow.
+  If you mention an issue or a merge request in a commit message, they will be shown
+  on their respective thread.
+- **Cherry-pick a commit:**
+In GitLab, you can
+[cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
+right from the UI.
+- **Revert a commit:**
+Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit)
+from the UI to a selected branch.
+
+## Repository size
+
+In GitLab.com, your repository size limit it 10GB. For other instances,
+the repository size is limited by your system administrators.
+
+You can also [reduce a repository size using Git](reducing_the_repo_size_using_git.md).
+
+## Contributors
+
+All the contributors to your codebase are displayed under your project's **Settings > Contributors**.
+
+They are ordered from the collaborator with the greatest number
+of commits to the fewest, and displayed on a nice graph:
+
+![contributors to code](img/contributors_graph.png)
+
+## Repository graph
+
+The repository graph displays visually the Git flow strategy used in that repository:
+
+![repository Git flow](img/repo_graph.png)
+
+Find it under your project's **Repository > Graph**.
+
+## Compare
+
+Select branches to compare and view the changes inline:
+
+![compare branches](img/compare_branches.png)
+
+Find it under your project's **Repository > Compare**.
+
+## Locked files (EEP)
+
+Lock your files to prevent any conflicting changes.
+
+[File Locking](https://docs.gitlab.com/ee/user/project/file_lock.html) is available only in
+[GitLab Enterprise Edition Premium](https://about.gitlab.com/gitlab-ee/).
+
+## Repository's API
+
+You can access your repos via [repository API](../../../api/repositories.md).
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
new file mode 100644
index 00000000000..08805a4dc99
--- /dev/null
+++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md
@@ -0,0 +1,81 @@
+# Reducing the repository size using Git
+
+A GitLab Entrerprise Edition administrator can set a [repository size limit][admin-repo-size]
+which will prevent you to exceed it.
+
+When a project has reached its size limit, you will not be able to push to it,
+create a new merge request, or merge existing ones. You will still be able to
+create new issues, and clone the project though. Uploading LFS objects will
+also be denied.
+
+In order to lift these restrictions, the administrator of the GitLab instance
+needs to increase the limit on the particular project that exceeded it or you
+need to instruct Git to rewrite changes.
+
+If you exceed the repository size limit, your first thought might be to remove
+some data, make a new commit and push back to the repository. Unfortunately,
+it's not so easy and that workflow won't work. Deleting files in a commit doesn't
+actually reduce the size of the repo since the earlier commits and blobs are
+still around. What you need to do is rewrite history with Git's
+[`filter-branch` option][gitscm].
+
+Note that even with that method, until `git gc` runs on the GitLab side, the
+"removed" commits and blobs will still be around. And if a commit was ever
+included in an MR, or if a build was run for a commit, or if a user commented
+on it, it will be kept around too. So, in these cases the size will not decrease.
+
+The only fool proof way to actually decrease the repository size is to prune all
+the unneeded stuff locally, and then create a new project on GitLab and start
+using that instead.
+
+With that being said, you can try reducing your repository size with the
+following method.
+
+## Using `git filter-branch` to purge files
+
+>
+**Warning:**
+Make sure to first make a copy of your repository since rewriting history will
+purge the files and information you are about to delete. Also make sure to
+inform any collaborators to not use `pull` after your changes, but use `rebase`.
+
+1. Navigate to your repository:
+
+    ```
+    cd my_repository/
+    ```
+
+1. Change to the branch you want to remove the big file from:
+
+    ```
+    git checkout master
+    ```
+
+1. Use `filter-branch` to remove the big file:
+
+    ```
+    git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD
+    ```
+
+1. Instruct Git to purge the unwanted data:
+
+    ```
+    git reflog expire --expire=now --all && git gc --prune=now --aggressive
+    ```
+
+1. Lastly, force push to the repository:
+
+    ```
+    git push --force origin master
+    ```
+
+Your repository should now be below the size limit.
+
+>**Note:**
+As an alternative to `filter-branch`, you can use the `bfg` tool with a
+command like: `bfg --delete-files path/to/big_file.mpg`. Read the
+[BFG Repo-Cleaner][bfg] documentation for more information.
+
+[admin-repo-size]: https://docs.gitlab.com/ee/user/admin_area/settings/account_and_limit_settings.html#repository-size-limit
+[bfg]: https://rtyley.github.io/bfg-repo-cleaner/
+[gitscm]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#The-Nuclear-Option:-filter-branch