Refine the README.

gitlabhq · Dec 23, 2016 · 30e6d79 · 30e6d79
1 parent a3712cc
commit 30e6d79
Showing 1 changed file with 38 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -1,54 +1,53 @@
-# GitLab Shell
+[![build status](https://gitlab.com/gitlab-org/gitlab-shell/badges/master/build.svg)](https://gitlab.com/gitlab-org/gitlab-shell/commits/master)
+[![Build Status](https://semaphoreapp.com/api/v1/projects/a71ddd46-a9cc-4062-875e-7ade19a44927/243336/badge.svg)](https://semaphoreapp.com/gitlabhq/gitlab-shell)
+[![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-shell.svg)](https://codeclimate.com/github/gitlabhq/gitlab-shell)
+[![Coverage Status](https://coveralls.io/repos/gitlabhq/gitlab-shell/badge.svg?branch=master)](https://coveralls.io/r/gitlabhq/gitlab-shell)
 
-## GitLab Shell handles git commands for GitLab
+# GitLab Shell
 
-GitLab Shell handles git commands for GitLab and modifies the list of authorized keys.
-GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh.
+GitLab Shell handles git commands for GitLab and modifies the server's list of 
+authorized keys. It is not a Unix shell nor a replacement for Bash or Zsh.
 
-When you access the GitLab server over ssh then GitLab Shell will:
+When predefined git commands (`git push`, `git pull`, `git annex`) are passed to 
+to the server over `ssh`, GitLab Shell will:
 
-1. Limits you to predefined git commands (git push, git pull, git annex).
 1. Call the GitLab Rails API to check if you are authorized
-1. It will execute the pre-receive hooks (called Git Hooks in GitLab Enterprise Edition)
-1. It will execute the action you requested
+1. Execute the pre-receive hooks (called "Git Hooks" in GitLab Enterprise Edition)
+1. Execute the action you requested
 1. Process the GitLab post-receive actions
 1. Process any custom post-receive actions
 
-If you access a GitLab server over http(s) what happens depends on if you pull from or push to the git repository.
-If you pull from git repositories over http(s) the GitLab Rails app will completely handle the authentication and execution.
-If you push to git repositories over http(s) the GitLab Rails app will not handle any authentication or execution but it will delegate the following to GitLab Shell:
+These steps are carried out differently for push and pull requests made over http(s):
 
-1. Call the GitLab Rails API to check if you are authorized
-1. It will execute the pre-receive hooks (called Git Hooks in GitLab Enterprise Edition)
-1. It will excute the action you requested
-1. Process the GitLab post-receive actions
-1. Process any custom post-receive actions
+**When you pull from a git repository over http(s)**, the GitLab Rails app handles 
+authentication and execution entirely on its own.
 
-Maybe you wonder why in the case of git push over http(s) the Rails app doesn't handle authentication before delegating to GitLab Shell.
-This is because GitLab Rails doesn't have the logic to interpret git push commands.
-The idea is to have these interpretation code in only one place and this is GitLab Shell so we can reuse it for ssh access.
-Actually GitLab Shell executes all git push commands without checking authorizations and relies on the pre-receive hooks to check authorizations.
-When you do a git pull command the authorizations are checked before executing the commands (either in GitLab Rails or GitLab Shell with an API call to GitLab Rails).
-The authorization checks for git pull are much simpler since you only have to check if a user can access the repo (no need to check branch permissions).
+**When you push to a git repository over http(s)**, the GitLab Rails app first 
+delegates authentication and execution to GitLab Shell.
 
-An overview of the four cases described above:
+This is because GitLab Rails doesn't have logic for interpreting git push 
+commands over http(s). This logic is kept in one place (GitLab Shell) so it can 
+be reused for commands passed over ssh.
 
-1. git pull over ssh  -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> execute git command
-1. git pull over http -> gitlab-rails (Authorization) -> accept or decline -> execute git command
-1. git push over ssh  -> gitlab-shell (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
-1. git push over http -> gitlab-rails (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
+Similarly, GitLab Shell does not have logic for conducting authorization. GitLab 
+Shell executes all push commands before conducting authorization, relying on 
+pre-receive hooks to do so by triggering API calls to gitlab-rails to check 
+authorization. 
 
-## Code status
+Steps for these four modes of access are represented here:
 
-[![build status](https://gitlab.com/gitlab-org/gitlab-shell/badges/master/build.svg)](https://gitlab.com/gitlab-org/gitlab-shell/commits/master)
-[![Build Status](https://semaphoreapp.com/api/v1/projects/a71ddd46-a9cc-4062-875e-7ade19a44927/243336/badge.svg)](https://semaphoreapp.com/gitlabhq/gitlab-shell)
-[![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-shell.svg)](https://codeclimate.com/github/gitlabhq/gitlab-shell)
-[![Coverage Status](https://coveralls.io/repos/gitlabhq/gitlab-shell/badge.svg?branch=master)](https://coveralls.io/r/gitlabhq/gitlab-shell)
+- **pull over ssh**  -> received by gitlab-shell -> API call to gitlab-rails (authorization) -> accept or decline -> git command executed
+- **pull over http(s)** -> received by gitlab-rails -> authorization handled internally by gitlab-rails -> accept or decline -> git command executed
+
+- **push over ssh**  -> received by gitlab-shell -> git command executed -> gitlab-shell pre-receive hook invoked -> API call to gitlab-rails (authorization) -> accept or decline push
+- **push over http(s)** -> received by gitlab-rails -> git command executed -> gitlab-shell pre-receive hook invoked -> API call to gitlab-rails (authorization) -> accept or decline push
 
-## Requirements
+## System Requirements
 
 **GitLab shell will always use your system ruby (normally located at /usr/bin/ruby) and will not use the ruby your installed with a ruby version manager (such as RVM).**
+
 It requires ruby 2.0 or higher.
+
 Please uninstall any old ruby versions from your system:
 
 ```
@@ -65,16 +64,17 @@ cd ruby-2.1.5
 make
 sudo make install
 ```
+## Shell Commands
 
-## Setup
+### Setup
 
     ./bin/install
 
-## Check
+### Check
 
     ./bin/check
 
-## Repos
+### Repos
 
 Add repo:
 
@@ -109,7 +109,7 @@ Gc repo:
 
     ./bin/gitlab-projects gc gitlab/gitlab-ci.git
 
-## Keys
+### Keys
 
 Add key:
 
@@ -128,6 +128,6 @@ Remove all keys from authorized_keys file:
 
     ./bin/gitlab-keys clear
 
-## Git LFS remark
+## A Note about Git LFS
 
 Starting with GitLab 8.12, GitLab supports Git LFS authentication through ssh.