6 files changed, 82 insertions, 2 deletions
diff --git a/doc/user/project/merge_requests/img/squash_edit_form.png b/doc/user/project/merge_requests/img/squash_edit_form.png
new file mode 100644
index 00000000000..496c6f44ea7
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_edit_form.png
diff --git a/doc/user/project/merge_requests/img/squash_mr_commits.png b/doc/user/project/merge_requests/img/squash_mr_commits.png
new file mode 100644
index 00000000000..5fc6a8c48bb
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_mr_commits.png
diff --git a/doc/user/project/merge_requests/img/squash_mr_widget.png b/doc/user/project/merge_requests/img/squash_mr_widget.png
new file mode 100644
index 00000000000..9cb458b2a35
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_mr_widget.png
diff --git a/doc/user/project/merge_requests/img/squash_squashed_commit.png b/doc/user/project/merge_requests/img/squash_squashed_commit.png
new file mode 100644
index 00000000000..0cf5875f82c
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_squashed_commit.png
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index 5932f5a2bc1..b75bcacc9d7 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -29,12 +29,12 @@ With GitLab merge requests, you can:
 - Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch
 - [Create new merge requests by email](#create-new-merge-requests-by-email)
 - Allow maintainers of the target project to push directly to the fork by [allowing edits from maintainers](maintainer_access.md)
+- [Squash and merge](squash_and_merge.md) for a cleaner commit history
 
 With **[GitLab Enterprise Edition][ee]**, you can also:
 
 - View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) **[PREMIUM]**
 - Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers **[STARTER]**
-- [Squash and merge](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html) for a cleaner commit history **[STARTER]**
 - Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html) **[STARTER]**
 
 ## Use cases
@@ -57,7 +57,7 @@ B. Consider you're a web developer writing a webpage for your company's:
 1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md)
 1. You request your web designers for their implementation
 1. You request the [approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your manager **[STARTER]**
-1. Once approved, your merge request is [squashed and merged](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) (Squash and Merge is available in GitLab Starter)
+1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
 1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production
 
 ## Merge requests per project
diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md
new file mode 100644
index 00000000000..a6efe893853
--- /dev/null
+++ b/doc/user/project/merge_requests/squash_and_merge.md
@@ -0,0 +1,80 @@
+# Squash and merge
+
+> [Introduced][ee-1024] in [GitLab Starter][ee] 8.17, and in [GitLab CE][ce] [11.0][ce-18956].
+
+Combine all commits of your merge request into one and retain a clean history.
+
+## Overview
+
+Squashing lets you tidy up the commit history of a branch when accepting a merge
+request. It applies all of the changes in the merge request as a single commit,
+and then merges that commit using the merge method set for the project.
+
+In other words, squashing a merge request turns a long list of commits:
+
+![List of commits from a merge request][mr-commits]
+
+Into a single commit on merge:
+
+![A squashed commit followed by a merge commit][squashed-commit]
+
+The squashed commit's commit message is the merge request title. And note that 
+the squashed commit is still followed by a merge commit, as the merge
+method for this example repository uses a merge commit. Squashing also works
+with the fast-forward merge strategy, see
+[squashing and fast-forward merge](#squash-and-fast-forward-merge) for more
+details.
+
+## Use cases
+
+When working on a feature branch, you sometimes want to commit your current
+progress, but don't really care about the commit messages. Those 'work in
+progress commits' don't necessarily contain important information and as such
+you'd rather not include them in your target branch. 
+
+With squash and merge, when the merge request is ready to be merged,
+all you have to do is enable squashing before you press merge to join
+the commits include in the merge request into a single commit.
+
+This way, the history of your base branch remains clean with
+meaningful commit messages and is simpler to [revert] if necessary.
+
+## Enabling squash for a merge request
+
+Anyone who can create or edit a merge request can choose for it to be squashed
+on the merge request form:
+
+![Squash commits checkbox on edit form][squash-edit-form]
+
+---
+
+This can then be overridden at the time of accepting the merge request:
+
+![Squash commits checkbox on accept merge request form][squash-mr-widget]
+
+## Commit metadata for squashed commits
+
+The squashed commit has the following metadata:
+
+* Message: the title of the merge request.
+* Author: the author of the merge request.
+* Committer: the user who initiated the squash.
+
+## Squash and fast-forward merge
+
+When a project has the [fast-forward merge setting enabled][ff-merge], the merge
+request must be able to be fast-forwarded without squashing in order to squash
+it. This is because squashing is only available when accepting a merge request,
+so a merge request may need to be rebased before squashing, even though
+squashing can itself be considered equivalent to rebasing.
+
+[ee-1024]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1024
+[ce-18956]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18956
+[mr-commits]: img/squash_mr_commits.png
+[squashed-commit]: img/squash_squashed_commit.png
+[squash-edit-form]: img/squash_edit_form.png
+[squash-mr-widget]: img/squash_mr_widget.png
+[ff-merge]: fast_forward_merge.md#enabling-fast-forward-merges
+[ce]: https://about.gitlab.com/products/
+[ee]: https://about.gitlab.com/products/
+[revert]: revert_changes.md