Consolidate the docs when changing a repo path

2 files changed, 98 insertions, 54 deletions

diff --git a/doc/user/project/index.md b/doc/user/project/index.md
index d4648a7600b..4c772c62f8d 100644
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -93,6 +93,9 @@ from your fork to the upstream project
 
 ## Project settings
 
+Set the project's visibility level and  the access levels to its various pages
+and perform actions like archiving, renaming or transferring a project.
+
 Read through the documentation on [project settings](settings/index.md).
 
 ## Import or export a project
@@ -105,53 +108,6 @@ Read through the documentation on [project settings](settings/index.md).
 - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data)
 - [Importing and exporting projects between GitLab instances](settings/import_export.md)
 
-## Transferring an existing project into another namespace
-
-You can transfer an existing project into a [group](../group/index.md) as long
-as you have at least **Master** [permissions](../permissions.md#permissions) to
-that group and if you are an **Owner** of the project.
-
-Similarly, if you are an owner of a group, you can transfer any of its projects
-under your own user.
-
-1. Navigate to your project's **Settings > General > Advanced settings**.
-1. Under "Transfer project", choose the namespace you want to transfer the
-   project to.
-1. Confirm the transfer by typing the project's path as instructed.
-
-Once done, you will be taken to the new project's namespace. At this point,
-read what happens with the
-[redirects from the old project to the new one](#redirects-when-transferring-or-renaming-projects).
-
-NOTE: **Note:**
-GitLab administrators can use the admin interface to move any project to any
-namespace if needed.
-
-## Renaming a project
-
-
-## Redirects when transferring or renaming projects
-
-When [transferring](#transfer-an-existing-project-into-a-group) or
-[renaming](#renaming-a-project) a project, it is essential to smoothly
-transition from the old location to the new one. GitLab provides two kinds
-of redirects: web UI and Git push/pull redirects.
-
-When visiting the old project's URL from your browser, you will be automatically
-to the new location.
-
-Starting with GitLab 10.3, Git actions will also redirect. This means that any
-build scripts, automation, or Git clients will continue to work after a
-rename, making any transition a lot smoother.
-
-Every time you push/pull to a repository that has changed its location,
-a redirect warning message to update your remote will be displayed instead of
-rejecting your action.
-
-NOTE: **Note:**
-To avoid pulling from or pushing to an entirely incorrect repository, the old
-path will be reserved.
-
 ## Project's members
 
 Learn how to [add members to your projects](members/index.md).
@@ -163,3 +119,32 @@ when a project is part of a group (under a
 [group namespace](../group/index.md#namespaces)).
 If you choose to leave a project you will no longer be a project
 member, therefore, unable to contribute.
+
+## Redirects when changing repository paths
+
+When a repository path changes, it is essential to smoothly transition from the
+old location to the new one. GitLab provides two kinds of redirects: the web UI
+and Git push/pull redirects.
+
+Depending on the situation, different things apply.
+
+When [transferring a project](settings/index.md#transferring-an-existing-project-into-another-namespace),
+or [renaming a user](../profile/index.md#changing-your-username) or
+[changing a group path](../group/index.md#changing-a-group-s-path):
+
+- **The redirect to the new URL is permanent**, which means that the original
+  namespace can't be claimed again by any group or user.
+- Existing web URLs for the namespace and anything under it (e.g., projects) will
+  redirect to the new URLs.
+- Starting with GitLab 10.3, existing Git remote URLs for projects under the
+  namespace will redirect to the new remote URL. Every time you push/pull to a
+  repository that has changed its location, a warning message to update
+  your remote will be displayed instead of rejecting your action.
+  This means that any automation scripts, or Git clients will continue to
+  work after a rename, making any transition a lot smoother.
+  To avoid pulling from or pushing to an entirely incorrect repository, the old
+  path will be reserved.
+
+When [renaming-a-repository](settings/index.md#renaming-a-repository), the same
+things apply, except for the Git push/pull actions which will be rejected with a
+warning message to change to the new remote URL.
diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md
index 2b6fde1e2a5..f01fa5b1860 100644
--- a/doc/user/project/settings/index.md
+++ b/doc/user/project/settings/index.md
@@ -1,11 +1,20 @@
 # Project settings
 
+NOTE: **Note:**
+Only project Masters and Admin users have the [permissions] to access a project
+settings.
+
 You can adjust your [project](../index.md) settings by navigating
 to your project's homepage and clicking **Settings**.
 
 ## General settings
 
-Adjust your project's path and name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and tags:
+Under a project's general settings you can find everything concerning the
+functionality of a project.
+
+### General project settings
+
+Adjust your project's name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and tags:
 
 ![general project settings](img/general_settings.png)
 
@@ -45,14 +54,64 @@ Here you can run housekeeping, archive, rename, transfer, or remove a project.
 
 #### Archiving a project
 
->**Note:** Only Project Owners and Admin users have the permission to archive a project
+NOTE: **Note:**
+Only project Owners and Admin users have the [permissions] to archive a project.
+
+An archived project will be hidden by default in the project listings.
+
+1. Navigate to your project's **Settings > General > Advanced settings**.
+1. Under "Archive project", hit the **Archive project** button.
+1. Confirm the action when asked to.
+
+An archived project can be fully restored and will therefore retain its
+repository and all associated resources whilst in an archived state.
+
+#### Renaming a repository
+
+NOTE: **Note:**
+Only project Masters and Admin users have the [permissions] to rename a
+repository. Not to be confused with a project's name where it can also be
+changed from the [general project settings](#general-project-settings).
+
+A project's repository name defines its URL (the one you use to access the
+project via a browser) and its place on the file disk where GitLab is installed.
+
+To rename a repository:
+
+1. Navigate to your project's **Settings > General > Advanced settings**.
+1. Under "Rename repository", change the "Path" to your liking.
+1. Hit **Rename project**.
+
+Remember that this can have unintended side effects since everyone with the
+old URL will not be able to push or pull. Read more about what happens with the
+[redirects when renaming repositories](../index.md#redirects-when-changing-repository-paths).
+
+#### Transferring an existing project into another namespace
+
+NOTE: **Note:**
+Only project Owners and Admin users have the [permissions] to transfer a project.
+
+You can transfer an existing project into a [group](../../group/index.md) if:
+
+1. you have at least **Master** [permissions] to that group
+1. you are an **Owner** of the project.
+
+Similarly, if you are an owner of a group, you can transfer any of its projects
+under your own user.
 
-It's possible to mark a project as archived via the Project Settings. An archived project will be hidden by default in the project listings.
+To transfer a project:
 
-An archived project can be fully restored and will therefore retain it's repository and all associated resources whilst in an archived state.
+1. Navigate to your project's **Settings > General > Advanced settings**.
+1. Under "Transfer project", choose the namespace you want to transfer the
+   project to.
+1. Confirm the transfer by typing the project's path as instructed.
 
-#### Renaming a project
+Once done, you will be taken to the new project's namespace. At this point,
+read what happens with the
+[redirects from the old project to the new one](../index.md#redirects-when-changing-repository-paths).
 
->**Note:** Only Project Owners and Admin users have the permission to rename a project
+NOTE: **Note:**
+GitLab administrators can use the admin interface to move any project to any
+namespace if needed.
 
-It's possible to rename a project from "Rename repository" or "Transfer project" sections. When doing so, you will need to update your local repositories to point to the new location, otherwise Git operations will be rejected.
+[permissions]: ../../permissions.md##project-members-permissions