Refactor Git troubleshooting docsdocs/troubleshooting-git

1 files changed, 47 insertions, 48 deletions

diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md
index 7c2d0f2a147..8555c5e91ea 100644
--- a/doc/topics/git/troubleshooting_git.md
+++ b/doc/topics/git/troubleshooting_git.md
@@ -1,83 +1,82 @@
 # Troubleshooting Git
 
 Sometimes things don't work the way they should or as you might expect when
-you're using Git. Here are some tips on troubleshooting and resolving issues 
+you're using Git. Here are some tips on troubleshooting and resolving issues
 with Git.
 
-## Error Messages
+## Broken pipe errors on git push
 
-### ‘Broken pipe’ Errors on Git Push
-
-‘Broken pipe’ errors can occur when attempting to push to a remote repository:
+'Broken pipe' errors can occur when attempting to push to a remote repository.
+When pushing you will usually see:
 
 ```
 Write failed: Broken pipe
 fatal: The remote end hung up unexpectedly
 ```
 
-#### If pushing over HTTP
+To fix this issue, here are some possible solutions.
+
+### Increase the POST buffer size in Git
 
-Try increasing the POST buffer size in Git configuration:
+**If pushing over HTTP**, you can try increasing the POST buffer size in Git's
+configuration. Open a terminal and enter:
 
 ```sh
 git config http.postBuffer 52428800
 ```
 
-The value is specified in bytes, so in the above case the buffer size has been 
+The value is specified in bytes, so in the above case the buffer size has been
 set to 50MB. The default is 1MB.
 
-#### If pushing over SSH
+### Check your SSH configuration
 
-1. Check SSH configuration:
+**If pushing over SSH**, first check your SSH configuration as 'Broken pipe'
+errors can sometimes be caused by underlying issues with SSH (such as
+authentication). Make sure that SSH is correctly configured by following the
+instructions in the [SSH troubleshooting] docs.
 
-	‘Broken pipe’ errors can sometimes be caused by underlying issues with SSH 
-	(such as authentication), so first check that SSH is correctly configured by
-	following the instructions in [SSH Troubleshooting][SSH-Troubleshooting].
+There's another option where you can prevent session timeouts by configuring
+SSH 'keep alive' either on the client or on the server (if you are a GitLab
+admin and have access to the server).
 
-1. Prevent session timeouts by configuring SSH ‘keep alive’ either on the client
-	or on the server:
-	
-	>**Note:** configuring *both* the client and the server is unnecessary.
+NOTE: **Note:** configuring *both* the client and the server is unnecessary.
 
-	#### Configure SSH on the client
-	
-	**On Linux (ssh)**
-	
-	Edit `~/.ssh/config` (create the file if it doesn’t exist) and insert:
-	
-	```apache
-	Host your-gitlab-instance-url.com
-	  ServerAliveInterval 60 
-	  ServerAliveCountMax 5	
-	```
+**To configure SSH on the client side**:
 
-	**On Windows (PuTTY)**
+-  On UNIX, edit `~/.ssh/config` (create the file if it doesn’t exist) and
+   add or edit:
 
-	In your session properties, go to *Connection* and under 
-	`Sending of null packets to keep session active`, set 
-	`Seconds between keepalives (0 to turn off)` to 60.
+    ```
+    Host your-gitlab-instance-url.com
+      ServerAliveInterval 60
+      ServerAliveCountMax 5
+    ```
 
-	#### Configure SSH on the server
+- On Windows, if you are using PuTTY, go to your session properties, then
+  navigate to "Connection" and under "Sending of null packets to keep
+  session active", set "Seconds between keepalives (0 to turn off)" to `60`.
 
-	Edit `/etc/ssh/sshd_config` and insert:
-	
-	```apache
-	ClientAliveInterval 60
-	ClientAliveCountMax 5	
-	```
+**To configure SSH on the server side**, edit `/etc/ssh/sshd_config` and add:
 
-#### If 'pack-objects' type errors are also being displayed
+```
+ClientAliveInterval 60
+ClientAliveCountMax 5
+```
 
-1. Try to run a `git repack` before attempting to push to the remote repository again:
+### Running a git repack
 
-	```
-	git repack
-	git push 
-	```
+**If 'pack-objects' type errors are also being displayed**, you can try to
+run a `git repack` before attempting to push to the remote repository again:
+
+```sh
+git repack
+git push
+```
 
-1. If you’re running an older version of Git (< 2.9), consider upgrading Git to >= 2.9 
-(see ‘[Broken pipe when pushing to Git repository][Broken-Pipe]').
+### Upgrade your Git client
 
-[SSH-Troubleshooting]: https://docs.gitlab.com/ce/ssh/README.html#troubleshooting "SSH Troubleshooting"
+In case you're running an older version of Git (< 2.9), consider upgrading
+to >= 2.9 (see [Broken pipe when pushing to Git repository][Broken-Pipe]).
 
+[SSH troubleshooting]: ../../ssh/README.md#troubleshooting "SSH Troubleshooting"
 [Broken-Pipe]: https://stackoverflow.com/questions/19120120/broken-pipe-when-pushing-to-git-repository/36971469#36971469 "StackOverflow: 'Broken pipe when pushing to Git repository'"