From 45d104ab832e2c32ccbcf78ebe19ab5946ffd9d9 Mon Sep 17 00:00:00 2001
From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com>
Date: Tue, 29 Sep 2020 21:13:54 +0200
Subject: [PATCH 1/8] Document authentication for private packages

---
 doc/05-repositories.md                        |   2 +-
 .../authentication-for-private-packages.md    | 226 ++++++++++++++++++
 ...-satis.md => handling-private-packages.md} |  19 +-
 doc/articles/http-basic-authentication.md     |  59 -----
 4 files changed, 229 insertions(+), 77 deletions(-)
 create mode 100644 doc/articles/authentication-for-private-packages.md
 rename doc/articles/{handling-private-packages-with-satis.md => handling-private-packages.md} (92%)
 delete mode 100644 doc/articles/http-basic-authentication.md

diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index 12a9dced0..38b5ef6f5 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -507,7 +507,7 @@ package repository definitions. It will fetch all the packages that are
 `require`d and dump a `packages.json` that is your `composer` repository.
 
 Check [the satis GitHub repository](https://github.com/composer/satis) and
-the [Satis article](articles/handling-private-packages-with-satis.md) for more
+the [Satis article](articles/handling-private-packages.md) for more
 information.
 
 ### Artifact
diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
new file mode 100644
index 000000000..3201d3269
--- /dev/null
+++ b/doc/articles/authentication-for-private-packages.md
@@ -0,0 +1,226 @@
+<!--
+    tagline: Access privately hosted packages
+-->
+
+# Authentication for privately hosted packages
+
+Your [private package server](handling-private-packages.md) is probably secured with one
+or more authentication options. In order to allow your project to have access to these
+packages you will have to tell Composer how to authenticate with the server that hosts the
+package(s).
+
+# Authentication principles
+
+Whenever composer encounters a protected composer repository it will try to authenticate
+using already defined credentials first. When none of those credentials apply it will prompt
+for credentials instead otherwise overridden and save those (or a token if composer is able
+to retrieve one).
+
+|type|Generated by Prompt?|
+|---|---|
+|[http-basic](#http-basic)|yes|
+|[Inline http-basic](#inline-http-basic)|no|
+|[custom header](#custom-token-authentication)|no|
+|[gitlab-oauth](#gitlab-oauth)|yes|
+|[gitlab-token](#gitlab-token)|yes|
+
+Sometimes automatic authentication is not possible, or you may want to predefine
+authentication credentials.
+
+Credentials can be stored on 3 different places; in an auth.json for the project, a global
+auth.json or in the composer.json itself.
+
+## Authentication in auth.json per project
+
+In this authentication storage method, an 'auth.json' file will be present in the same folder
+as the projects' composer.json file. You can either create and edit this file using the
+command line or manually edit or create it.
+
+> **Note: Make sure the auth.json file is in the .gitignore** otherwise
+> other people will be able to abuse your credentials.
+
+## Global authentication credentials
+
+If you don't want to supply credentials for every project you work on, storing your credentials
+globally might be a better idea. These credentials are stored in a global auth.json in your
+composer home directory.
+
+### Command line global credential editing
+
+For all authentication methods it is possible to edit them using the command line;
+ - [http-basic](#command-line-http-basic)
+ - [Inline http-basic](#command-line-inline-http-basic)
+ - [gitlab-oauth](#command-line-gitlab-oauth)
+ - [gitlab-token](#command-line-gitlab-token)
+
+### Manually editing global authentication credentials
+
+> **Note:** It is not recommended to manually edit your authentication options as this might
+> result in invalid json. Instead preferably use [the command line](#command-line-global-credential-editing).
+
+To manually edit it:
+```shell script
+composer config --global --editor [--auth]
+```
+
+For specific authentication implementations, see their sections;
+ - [http-basic](#manual-http-basic)
+ - [Inline http-basic](#manual-inline-http-basic)
+ - [custom header](#manual-custom-token-authentication)
+ - [gitlab-oauth](#manual-gitlab-oauth)
+ - [gitlab-token](#manual-gitlab-token)
+
+Manually editing this file instead of using the command line may result in invalid json errors.
+To fix this you need to open the file in an editor and fix the error. To find the location of
+your global auth.json, execute:
+
+```shell script
+composer config --global --list
+```
+
+And look for the `[home]` section. (It is by default `~/.composer` or `%APPDATA%/Composer` on Windows)
+The folder will contain your global auth.json if it exists.
+
+You can open this file in your favorite editor and fix the error.
+
+## Authentication in composer.json file itself
+
+> **Note:** **This is not recommended** as these credentials are visible
+> to anyone who has access to the composer.json, either when it is shared through
+> a version control system like git or when an attacker gains (read) access to
+> your production server files.
+
+It is also possible to add credentials to a composer.json on a per-project basis in the 'config'
+section or directly to the repository definition.
+
+# Authentication methods
+
+## http-basic
+
+### Command line http-basic
+
+```shell script
+composer config [--global] http-basic.example.org username password
+```
+
+### Manual http-basic
+
+```shell script
+composer config [--global] --editor --auth
+```
+
+```json
+{
+    "http-basic": {
+        "example.org": {
+            "username": "username",
+            "password": "password"
+        }
+    }
+}
+```
+
+## Inline http-basic
+
+For the inline http-basic authentication method the credentials are not stored in a separate
+auth.json in the project or globally, but in the composer.json or global configuration
+in the same place where the composer repository definition is defined.
+
+### Command line inline http-basic
+
+```shell script
+composer config [--global] repositories composer.unique-name https://username:password@repo.example.org
+```
+
+### Manual inline http-basic
+
+```shell script
+composer config [--global] --editor
+```
+
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://username:password@example.org"
+        }
+    ]
+}
+```
+
+## Custom token authentication
+
+### Manual custom token authentication
+
+```shell script
+composer config [--global] --editor
+```
+
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://example.org",
+            "options":  {
+              "http": {
+                "header": [
+                  "API-TOKEN: YOUR-API-TOKEN"
+                ]
+              }
+            }
+        }
+    ]
+}
+```
+
+## gitlab-oauth
+
+> **Note:** For the gitlab authentication to work on private gitlab instances, the
+> "gitlab-domains" section should also contain the url.
+
+### Command line gitlab-oauth
+
+```shell script
+composer config [--global] gitlab-oauth.example.org token
+```
+
+### Manual gitlab-oauth
+
+```shell script
+composer config [--global] --editor --auth
+```
+
+```json
+{
+    "gitlab-oauth": {
+        "example.org": "token"
+    }
+}
+```
+
+## gitlab-token
+
+> **Note:** For the gitlab authentication to work on private gitlab instances, the
+> "gitlab-domains" section should also contain the url.
+
+### Command line gitlab-token
+
+```shell script
+composer config [--global] gitlab-token.example.org token
+```
+
+### Manual gitlab-token
+
+```shell script
+composer config [--global] --editor --auth
+```
+
+```json
+{
+    "gitlab-token": {
+        "example.org": "token"
+    }
+}
+```
diff --git a/doc/articles/handling-private-packages-with-satis.md b/doc/articles/handling-private-packages.md
similarity index 92%
rename from doc/articles/handling-private-packages-with-satis.md
rename to doc/articles/handling-private-packages.md
index 3ef604fe7..026097b2d 100644
--- a/doc/articles/handling-private-packages-with-satis.md
+++ b/doc/articles/handling-private-packages.md
@@ -213,23 +213,8 @@ Example using a custom HTTP Header field for token authentication:
 
 ### Authentication
 
-When your private repositories are password protected, you can store the
-authentication details permanently.  The first time Composer needs to
-authenticate against some domain it will prompt you for a username/password and
-then you will be asked whether you want to store it.
-
-The storage can be done either globally in the `COMPOSER_HOME/auth.json` file
-(`COMPOSER_HOME` defaults to `~/.composer` or `%APPDATA%/Composer` on Windows)
-or also in the project directory directly sitting besides your composer.json.
-
-You can also configure these by hand using the config command if you need to
-configure a production machine to be able to run non-interactive installs. For
-example to enter credentials for example.org one could type:
-
-    composer config http-basic.example.org username password
-
-That will store it in the current directory's auth.json, but if you want it
-available globally you can use the `--global` (`-g`) flag.
+Authentication can by handled in several different ways. More can be read about it
+[here](authentication-for-private-packages.md)
 
 ### Downloads
 
diff --git a/doc/articles/http-basic-authentication.md b/doc/articles/http-basic-authentication.md
deleted file mode 100644
index fad17d28f..000000000
--- a/doc/articles/http-basic-authentication.md
+++ /dev/null
@@ -1,59 +0,0 @@
-<!--
-    tagline: Access privately hosted packages
--->
-
-# HTTP basic authentication
-
-Your [Satis or Private Packagist](handling-private-packages-with-satis.md) server
-could be secured with http basic authentication. In order to allow your project
-to have access to these packages you will have to tell composer how to
-authenticate with your credentials.
-
-The simplest way to provide your credentials is providing your set
-of credentials inline with the repository specification such as:
-
-```json
-{
-    "repositories": [
-        {
-            "type": "composer",
-            "url": "https://extremely:secret@repo.example.org"
-        }
-    ]
-}
-```
-
-This will basically teach composer how to authenticate automatically
-when reading packages from the provided composer repository.
-
-This does not work for everybody especially when you don't want to
-hard code your credentials into your composer.json. There is a second
-way to provide these details and it is via interaction. If you don't
-provide the authentication credentials composer will prompt you upon
-connection to enter the username and password.
-
-The third way if you want to pre-configure it is via an `auth.json` file
-located in your `COMPOSER_HOME` or besides your `composer.json`.
-
-The file should contain a set of hostnames followed each with their own
-username/password pairs, for example:
-
-```json
-{
-    "http-basic": {
-        "repo.example1.org": {
-            "username": "my-username1",
-            "password": "my-secret-password1"
-        },
-        "repo.example2.org": {
-            "username": "my-username2",
-            "password": "my-secret-password2"
-        }
-    }
-}
-```
-
-The main advantage of the auth.json file is that it can be gitignored so
-that every developer in your team can place their own credentials in there,
-which makes revocation of credentials much easier than if you all share the
-same.

From 6a2f91a0e0f82ff6ec606e955474ad8874963dac Mon Sep 17 00:00:00 2001
From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com>
Date: Wed, 30 Sep 2020 19:02:58 +0200
Subject: [PATCH 2/8] Process review comments

---
 doc/05-repositories.md                        |  2 +-
 .../authentication-for-private-packages.md    | 24 +++++++++----------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index 38b5ef6f5..c7129a6c6 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -507,7 +507,7 @@ package repository definitions. It will fetch all the packages that are
 `require`d and dump a `packages.json` that is your `composer` repository.
 
 Check [the satis GitHub repository](https://github.com/composer/satis) and
-the [Satis article](articles/handling-private-packages.md) for more
+the [handling private packages article](articles/handling-private-packages.md) for more
 information.
 
 ### Artifact
diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
index 3201d3269..3762465dd 100644
--- a/doc/articles/authentication-for-private-packages.md
+++ b/doc/articles/authentication-for-private-packages.md
@@ -27,22 +27,22 @@ to retrieve one).
 Sometimes automatic authentication is not possible, or you may want to predefine
 authentication credentials.
 
-Credentials can be stored on 3 different places; in an auth.json for the project, a global
-auth.json or in the composer.json itself.
+Credentials can be stored on 3 different places; in an `auth.json` for the project, a global
+`auth.json` or in the `composer.json` itself.
 
 ## Authentication in auth.json per project
 
-In this authentication storage method, an 'auth.json' file will be present in the same folder
-as the projects' composer.json file. You can either create and edit this file using the
+In this authentication storage method, an `auth.json` file will be present in the same folder
+as the projects' `composer.json` file. You can either create and edit this file using the
 command line or manually edit or create it.
 
-> **Note: Make sure the auth.json file is in the .gitignore** otherwise
+> **Note: Make sure the `auth.json` file is in the `.gitignore`** otherwise
 > other people will be able to abuse your credentials.
 
 ## Global authentication credentials
 
 If you don't want to supply credentials for every project you work on, storing your credentials
-globally might be a better idea. These credentials are stored in a global auth.json in your
+globally might be a better idea. These credentials are stored in a global `auth.json` in your
 composer home directory.
 
 ### Command line global credential editing
@@ -72,14 +72,14 @@ For specific authentication implementations, see their sections;
 
 Manually editing this file instead of using the command line may result in invalid json errors.
 To fix this you need to open the file in an editor and fix the error. To find the location of
-your global auth.json, execute:
+your global `auth.json`, execute:
 
 ```shell script
 composer config --global --list
 ```
 
 And look for the `[home]` section. (It is by default `~/.composer` or `%APPDATA%/Composer` on Windows)
-The folder will contain your global auth.json if it exists.
+The folder will contain your global `auth.json` if it exists.
 
 You can open this file in your favorite editor and fix the error.
 
@@ -90,7 +90,7 @@ You can open this file in your favorite editor and fix the error.
 > a version control system like git or when an attacker gains (read) access to
 > your production server files.
 
-It is also possible to add credentials to a composer.json on a per-project basis in the 'config'
+It is also possible to add credentials to a `composer.json` on a per-project basis in the `config`
 section or directly to the repository definition.
 
 # Authentication methods
@@ -123,7 +123,7 @@ composer config [--global] --editor --auth
 ## Inline http-basic
 
 For the inline http-basic authentication method the credentials are not stored in a separate
-auth.json in the project or globally, but in the composer.json or global configuration
+`auth.json` in the project or globally, but in the `composer.json` or global configuration
 in the same place where the composer repository definition is defined.
 
 ### Command line inline http-basic
@@ -178,7 +178,7 @@ composer config [--global] --editor
 ## gitlab-oauth
 
 > **Note:** For the gitlab authentication to work on private gitlab instances, the
-> "gitlab-domains" section should also contain the url.
+> `gitlab-domains` section should also contain the url.
 
 ### Command line gitlab-oauth
 
@@ -203,7 +203,7 @@ composer config [--global] --editor --auth
 ## gitlab-token
 
 > **Note:** For the gitlab authentication to work on private gitlab instances, the
-> "gitlab-domains" section should also contain the url.
+> `gitlab-domains` section should also contain the url.
 
 ### Command line gitlab-token
 

From e90e08dc26e21e1cdb255082475ebf94a0588234 Mon Sep 17 00:00:00 2001
From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com>
Date: Mon, 5 Oct 2020 10:45:41 +0200
Subject: [PATCH 3/8] Revert rename of handling private packages with satis
 page to split off to new CR.

---
 doc/05-repositories.md                                          | 2 +-
 doc/articles/authentication-for-private-packages.md             | 2 +-
 ...vate-packages.md => handling-private-packages-with-satis.md} | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename doc/articles/{handling-private-packages.md => handling-private-packages-with-satis.md} (100%)

diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index c7129a6c6..8f372a60e 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -507,7 +507,7 @@ package repository definitions. It will fetch all the packages that are
 `require`d and dump a `packages.json` that is your `composer` repository.
 
 Check [the satis GitHub repository](https://github.com/composer/satis) and
-the [handling private packages article](articles/handling-private-packages.md) for more
+the [handling private packages article](articles/handling-private-packages-with-satis.md) for more
 information.
 
 ### Artifact
diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
index 3762465dd..05b1e1d27 100644
--- a/doc/articles/authentication-for-private-packages.md
+++ b/doc/articles/authentication-for-private-packages.md
@@ -4,7 +4,7 @@
 
 # Authentication for privately hosted packages
 
-Your [private package server](handling-private-packages.md) is probably secured with one
+Your [private package server](handling-private-packages-with-satis.md) is probably secured with one
 or more authentication options. In order to allow your project to have access to these
 packages you will have to tell Composer how to authenticate with the server that hosts the
 package(s).
diff --git a/doc/articles/handling-private-packages.md b/doc/articles/handling-private-packages-with-satis.md
similarity index 100%
rename from doc/articles/handling-private-packages.md
rename to doc/articles/handling-private-packages-with-satis.md

From 2afd7e591314d3e100d3791886a09f0285db0c2d Mon Sep 17 00:00:00 2001
From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com>
Date: Mon, 5 Oct 2020 14:09:58 +0200
Subject: [PATCH 4/8] Readded http basic auth page with link to new page so old
 links don't break

---
 doc/articles/http-basic-authentication.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 doc/articles/http-basic-authentication.md

diff --git a/doc/articles/http-basic-authentication.md b/doc/articles/http-basic-authentication.md
new file mode 100644
index 000000000..c8456a029
--- /dev/null
+++ b/doc/articles/http-basic-authentication.md
@@ -0,0 +1,7 @@
+<!--
+    tagline: Access privately hosted packages
+-->
+
+# HTTP basic authentication
+
+This documentation has moved to the generic ["authentication in private packages documentation" page](authentication-for-private-packages.md#http-basic)

From 78f9dd73ced80410301733bb681d9947cdbdf023 Mon Sep 17 00:00:00 2001
From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com>
Date: Mon, 5 Oct 2020 21:11:16 +0200
Subject: [PATCH 5/8] Rename handling private packages page to better reflect
 content

---
 doc/05-repositories.md                                          | 2 +-
 doc/articles/authentication-for-private-packages.md             | 2 +-
 ...vate-packages-with-satis.md => handling-private-packages.md} | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename doc/articles/{handling-private-packages-with-satis.md => handling-private-packages.md} (100%)

diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index 8f372a60e..c7129a6c6 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -507,7 +507,7 @@ package repository definitions. It will fetch all the packages that are
 `require`d and dump a `packages.json` that is your `composer` repository.
 
 Check [the satis GitHub repository](https://github.com/composer/satis) and
-the [handling private packages article](articles/handling-private-packages-with-satis.md) for more
+the [handling private packages article](articles/handling-private-packages.md) for more
 information.
 
 ### Artifact
diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
index 05b1e1d27..3762465dd 100644
--- a/doc/articles/authentication-for-private-packages.md
+++ b/doc/articles/authentication-for-private-packages.md
@@ -4,7 +4,7 @@
 
 # Authentication for privately hosted packages
 
-Your [private package server](handling-private-packages-with-satis.md) is probably secured with one
+Your [private package server](handling-private-packages.md) is probably secured with one
 or more authentication options. In order to allow your project to have access to these
 packages you will have to tell Composer how to authenticate with the server that hosts the
 package(s).
diff --git a/doc/articles/handling-private-packages-with-satis.md b/doc/articles/handling-private-packages.md
similarity index 100%
rename from doc/articles/handling-private-packages-with-satis.md
rename to doc/articles/handling-private-packages.md

From 5b34a61b4a9802fd18d02c49a538b3f7fea90469 Mon Sep 17 00:00:00 2001
From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com>
Date: Mon, 5 Oct 2020 21:13:02 +0200
Subject: [PATCH 6/8] Capitalize composer name occurrences

---
 doc/articles/authentication-for-private-packages.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
index 3762465dd..9c7e7633e 100644
--- a/doc/articles/authentication-for-private-packages.md
+++ b/doc/articles/authentication-for-private-packages.md
@@ -11,9 +11,9 @@ package(s).
 
 # Authentication principles
 
-Whenever composer encounters a protected composer repository it will try to authenticate
+Whenever Composer encounters a protected Composer repository it will try to authenticate
 using already defined credentials first. When none of those credentials apply it will prompt
-for credentials instead otherwise overridden and save those (or a token if composer is able
+for credentials instead otherwise overridden and save those (or a token if Composer is able
 to retrieve one).
 
 |type|Generated by Prompt?|
@@ -43,7 +43,7 @@ command line or manually edit or create it.
 
 If you don't want to supply credentials for every project you work on, storing your credentials
 globally might be a better idea. These credentials are stored in a global `auth.json` in your
-composer home directory.
+Composer home directory.
 
 ### Command line global credential editing
 
@@ -124,7 +124,7 @@ composer config [--global] --editor --auth
 
 For the inline http-basic authentication method the credentials are not stored in a separate
 `auth.json` in the project or globally, but in the `composer.json` or global configuration
-in the same place where the composer repository definition is defined.
+in the same place where the Composer repository definition is defined.
 
 ### Command line inline http-basic
 

From 42ee8a7331a1b73e240ed0daf171b2db56b661ab Mon Sep 17 00:00:00 2001
From: Jordi Boggiano <j.boggiano@seld.be>
Date: Mon, 12 Oct 2020 15:58:53 +0200
Subject: [PATCH 7/8] Delete http-basic-authentication.md

---
 doc/articles/http-basic-authentication.md | 7 -------
 1 file changed, 7 deletions(-)
 delete mode 100644 doc/articles/http-basic-authentication.md

diff --git a/doc/articles/http-basic-authentication.md b/doc/articles/http-basic-authentication.md
deleted file mode 100644
index c8456a029..000000000
--- a/doc/articles/http-basic-authentication.md
+++ /dev/null
@@ -1,7 +0,0 @@
-<!--
-    tagline: Access privately hosted packages
--->
-
-# HTTP basic authentication
-
-This documentation has moved to the generic ["authentication in private packages documentation" page](authentication-for-private-packages.md#http-basic)

From 7ab24bec94adedb1c501bde9c05ca7434eb7423d Mon Sep 17 00:00:00 2001
From: Jordi Boggiano <j.boggiano@seld.be>
Date: Mon, 12 Oct 2020 16:09:21 +0200
Subject: [PATCH 8/8] Minor updates

---
 .../authentication-for-private-packages.md    | 40 +++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
index 9c7e7633e..8e51ab7de 100644
--- a/doc/articles/authentication-for-private-packages.md
+++ b/doc/articles/authentication-for-private-packages.md
@@ -13,14 +13,13 @@ package(s).
 
 Whenever Composer encounters a protected Composer repository it will try to authenticate
 using already defined credentials first. When none of those credentials apply it will prompt
-for credentials instead otherwise overridden and save those (or a token if Composer is able
-to retrieve one).
+for credentials and save them (or a token if Composer is able to retrieve one).
 
 |type|Generated by Prompt?|
 |---|---|
 |[http-basic](#http-basic)|yes|
 |[Inline http-basic](#inline-http-basic)|no|
-|[custom header](#custom-token-authentication)|no|
+|[Custom header](#custom-token-authentication)|no|
 |[gitlab-oauth](#gitlab-oauth)|yes|
 |[gitlab-token](#gitlab-token)|yes|
 
@@ -36,8 +35,8 @@ In this authentication storage method, an `auth.json` file will be present in th
 as the projects' `composer.json` file. You can either create and edit this file using the
 command line or manually edit or create it.
 
-> **Note: Make sure the `auth.json` file is in the `.gitignore`** otherwise
-> other people will be able to abuse your credentials.
+> **Note: Make sure the `auth.json` file is in `.gitignore`** to avoid
+> leaking credentials into your git history.
 
 ## Global authentication credentials
 
@@ -58,8 +57,9 @@ For all authentication methods it is possible to edit them using the command lin
 > **Note:** It is not recommended to manually edit your authentication options as this might
 > result in invalid json. Instead preferably use [the command line](#command-line-global-credential-editing).
 
-To manually edit it:
-```shell script
+To manually edit it, run:
+
+```sh
 composer config --global --editor [--auth]
 ```
 
@@ -74,7 +74,7 @@ Manually editing this file instead of using the command line may result in inval
 To fix this you need to open the file in an editor and fix the error. To find the location of
 your global `auth.json`, execute:
 
-```shell script
+```sh
 composer config --global --list
 ```
 
@@ -91,7 +91,7 @@ You can open this file in your favorite editor and fix the error.
 > your production server files.
 
 It is also possible to add credentials to a `composer.json` on a per-project basis in the `config`
-section or directly to the repository definition.
+section or directly in the repository definition.
 
 # Authentication methods
 
@@ -99,13 +99,13 @@ section or directly to the repository definition.
 
 ### Command line http-basic
 
-```shell script
+```sh
 composer config [--global] http-basic.example.org username password
 ```
 
 ### Manual http-basic
 
-```shell script
+```sh
 composer config [--global] --editor --auth
 ```
 
@@ -128,13 +128,13 @@ in the same place where the Composer repository definition is defined.
 
 ### Command line inline http-basic
 
-```shell script
+```sh
 composer config [--global] repositories composer.unique-name https://username:password@repo.example.org
 ```
 
 ### Manual inline http-basic
 
-```shell script
+```sh
 composer config [--global] --editor
 ```
 
@@ -153,7 +153,7 @@ composer config [--global] --editor
 
 ### Manual custom token authentication
 
-```shell script
+```sh
 composer config [--global] --editor
 ```
 
@@ -178,17 +178,17 @@ composer config [--global] --editor
 ## gitlab-oauth
 
 > **Note:** For the gitlab authentication to work on private gitlab instances, the
-> `gitlab-domains` section should also contain the url.
+> [`gitlab-domains`](../06-config.md#gitlab-domains) section should also contain the url.
 
 ### Command line gitlab-oauth
 
-```shell script
+```sh
 composer config [--global] gitlab-oauth.example.org token
 ```
 
 ### Manual gitlab-oauth
 
-```shell script
+```sh
 composer config [--global] --editor --auth
 ```
 
@@ -203,17 +203,17 @@ composer config [--global] --editor --auth
 ## gitlab-token
 
 > **Note:** For the gitlab authentication to work on private gitlab instances, the
-> `gitlab-domains` section should also contain the url.
+> [`gitlab-domains`](../06-config.md#gitlab-domains) section should also contain the url.
 
 ### Command line gitlab-token
 
-```shell script
+```sh
 composer config [--global] gitlab-token.example.org token
 ```
 
 ### Manual gitlab-token
 
-```shell script
+```sh
 composer config [--global] --editor --auth
 ```