From 4fcc0057cd1df1ee7153eb093afaf067f52d805c Mon Sep 17 00:00:00 2001 From: James Milligan Date: Thu, 6 Aug 2020 20:41:26 +0100 Subject: [PATCH] Fix typos in documentation --- Directory.Build.props | 2 +- docs/architecture.md | 12 ++++++------ docs/configuration.md | 4 ++-- docs/environment.md | 4 ++-- docs/faq.md | 2 +- docs/hostprovider.md | 22 +++++++++++----------- docs/netconfig.md | 10 +++++----- 7 files changed, 28 insertions(+), 28 deletions(-) diff --git a/Directory.Build.props b/Directory.Build.props index d1cce39d6..4ff259566 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -5,7 +5,7 @@ windows osx diff --git a/docs/architecture.md b/docs/architecture.md index 750e21230..9c33ac348 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -96,11 +96,11 @@ specific host provider. This was done to allow any service that may wish to in the future integrate with Microsoft Accounts or Azure Active Directory can make use of this reusable authentication component. -Since MSAL.NET includes embedded GUI on Windows (when targeting .NET Frameonly +Since MSAL.NET includes embedded GUI on Windows (when targeting .NET Framework only - see note above) we have no helper executable on Windows. However, on macOS the `MicrosoftAuthentication` component shells out to a native macOS helper that completely takes over all authentication flows using the older ADAL -Objective-C libary. This was done because MSAL.NET does not offer the same level +Objective-C library. This was done because MSAL.NET does not offer the same level of integration for [MDM](https://en.wikipedia.org/wiki/Mobile_device_management) purposes, as well as lacking an embedded UI on non-Windows platforms. As MSAL.NET continues to evolve we hope to replace the ADAL/macOS helper @@ -164,7 +164,7 @@ instance of the provider to the `Application` object via the `RegisterProvider` method [in `Microsoft.Git.CredentialManager.Program`](../src/shared/Git-Credential-Manager/Program.cs). The `GenericHostProvider` is registered last so that it can handle all other HTTP-based remotes as a catch-all, and provide basic username/password auth and -detect the presense of Windows Integrated Authentication (Kerberos, NTLM, +detect the presence of Windows Integrated Authentication (Kerberos, NTLM, Negotiate) support (1). For each invocation of GCM Core, the first argument on the command-line is @@ -174,7 +174,7 @@ from Git (over standard input) is deserialized and the command is executed (2). The `Get|Store|EraseCommand`s consult the host provider registry for the most appropriate host provider. The default registry implementation select the a host provider by asking each registered provider in turn if they understand the -request. The provider selection can be overriden by the user via the +request. The provider selection can be overridden by the user via the [`credential.provider`](configuration.md#credentialprovider) or [`GCM_PROVIDER`](environment.md#GCM_PROVIDER) configuration and environment variable respectively (3)). @@ -210,7 +210,7 @@ custom caches on an `erase` request, without having to reimplement the lookup/store credential logic. Host providers are queried in turn (registration order) via the -`IHostProvider.IsSupported` method and passed the input recieved from Git. If +`IHostProvider.IsSupported` method and passed the input received from Git. If the provider recognises the request, for example by a matching known host name, they can return `true`. If the provider wants to cancel and abort an authentication request, for example if this is a HTTP (not HTTPS) request for a @@ -266,7 +266,7 @@ caught, a non-zero exit code returned, and the error message printed with the "fatal:" prefix. For errors originating from interop/native code, you should throw an exception of the `InteropException` type. Error messages in exceptions should be human readable. When there is a known or user-fixable issue, -instructions on how to self-rememdy the issue, or links to relevant +instructions on how to self-remedy the issue, or links to relevant documentation should be given. Warnings can be emitted over the standard error stream diff --git a/docs/configuration.md b/docs/configuration.md index 179507d9d..432ac4571 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -16,7 +16,7 @@ GCM Core will only be used by Git if it is installed and configured (`credential > `credential.microsoft.visualstudio.com.namespace` is more specific than `credential.visualstudio.com.namespace`, which is more specific than `credential.namespace`. -In the examples above, the `credential.namespace` setting would affect any remote repository; the `credential.visualstudio.com.namespace` would affect any remote repository in the domain, and/or any subdomain (including `www.`) of, 'visualstudio.com'; where as the the `credential.microsoft.visualstudio.com.namespace` setting would only be applied to remote repositories hosted at 'microsoft.visualstudio.com'. +In the examples above, the `credential.namespace` setting would affect any remote repository; the `credential.visualstudio.com.namespace` would affect any remote repository in the domain, and/or any subdomain (including `www.`) of, 'visualstudio.com'; where as the `credential.microsoft.visualstudio.com.namespace` setting would only be applied to remote repositories hosted at 'microsoft.visualstudio.com'. For the complete list of settings GCM Core understands, see the list below. @@ -26,7 +26,7 @@ For the complete list of settings GCM Core understands, see the list below. Permit or disable GCM Core from interacting with the user (showing GUI or TTY prompts). If interaction is required but has been disabled, an error is returned. -This can be helpful when using GCM Core in headless and unattended environments, such as build servers, where it would be preferable to fail than to hang indefinately waiting for a non-existent user. +This can be helpful when using GCM Core in headless and unattended environments, such as build servers, where it would be preferable to fail than to hang indefinitely waiting for a non-existent user. To disable interactivity set this to `false` or `0`. diff --git a/docs/environment.md b/docs/environment.md index c60c42c1c..7958235cc 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -41,7 +41,7 @@ _No configuration equivalent._ ### GCM_TRACE_SECRETS -Enables tracing of secret and senstive information, which is by default masked in trace output. +Enables tracing of secret and sensitive information, which is by default masked in trace output. Requires that `GCM_TRACE` is also enabled. #### Example @@ -125,7 +125,7 @@ _No configuration equivalent._ Permit or disable GCM Core from interacting with the user (showing GUI or TTY prompts). If interaction is required but has been disabled, an error is returned. -This can be helpful when using GCM Core in headless and unattended environments, such as build servers, where it would be preferable to fail than to hang indefinately waiting for a non-existent user. +This can be helpful when using GCM Core in headless and unattended environments, such as build servers, where it would be preferable to fail than to hang indefinitely waiting for a non-existent user. To disable interactivity set this to `false` or `0`. diff --git a/docs/faq.md b/docs/faq.md index 9bc71295d..5f2cb2a72 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -39,7 +39,7 @@ No. Git Credential Manager for Windows (GCM Windows) will continue to be support ### Q: Does this mean the Java-based GCM for Mac/Linux is deprecated? -Yes. Usage of Git Credential Manager for Mac and Linux (Java GCM) should be replaced with SSH keys. If you wish to take part in the public preview of GCM Core on macOS please feel free to install the latest preview release and give feedback! Otherwise, using SSH would be prefered on macOS and Linux to Java GCM. +Yes. Usage of Git Credential Manager for Mac and Linux (Java GCM) should be replaced with SSH keys. If you wish to take part in the public preview of GCM Core on macOS please feel free to install the latest preview release and give feedback! Otherwise, using SSH would be preferred on macOS and Linux to Java GCM. SSH configuration instructions: diff --git a/docs/hostprovider.md b/docs/hostprovider.md index af68e5146..d370a4bd2 100644 --- a/docs/hostprovider.md +++ b/docs/hostprovider.md @@ -9,7 +9,7 @@ Last updated|2020-06-22 ## Abstract Git Credential Manger Core, the cross-platform and cross-host Git credential -helper, can be extended to support any Git hosting service allowing seemless +helper, can be extended to support any Git hosting service allowing seamless authentication to secured Git repositories by implementing and registering a "host provider". @@ -65,7 +65,7 @@ Mac/Linux" or "GCM Mac/Linux". OAuth2 [[RFC6749](https://tools.ietf.org/html/rfc6749)] "access tokens" are abbreviated to "ATs" and "refresh tokens" to "RTs". "Personal Access Tokens" are -abbreivated to "PATs". +abbreviated to "PATs". ## 2. Implementation @@ -109,7 +109,7 @@ register providers with by calling the `RegisterProvider` method. #### 2.1.2. Ordering The default host provider registry in GCM Core will call each host provider in -the order they were registered in, unless the user has overriden the provider +the order they were registered in, unless the user has overridden the provider selection process. There are no rules or restrictions on the ordering of host providers, except @@ -120,9 +120,9 @@ way. ### 2.2. Handling Requests The `IsSupported` method will be called on all registered host providers in-turn -on the invokation of a `get`, `store`, or `erase` request. The first host +on the invocation of a `get`, `store`, or `erase` request. The first host provider to return `true` will be called upon to handle the specific request. -If the user has overriden the host provider selection process, a specific host +If the user has overridden the host provider selection process, a specific host provider may be selected instead, and the `IsSupported` method will NOT be called. @@ -145,7 +145,7 @@ example "HTTP is not secure, please use HTTPS". ### 2.3. Retrieving Credentials The `GetCredentialAsync` method will be called when a `get` request is made. -The method MUST return an instance of an `ICredential` capable of fufilling the +The method MUST return an instance of an `ICredential` capable of fulfilling the specific access request. The argument passed to `GetCredentialAsync` contains properties indicating the required `protocol` and `host` for this request. The `username` and `path` properties are OPTIONAL, however if they are present, they @@ -158,7 +158,7 @@ The host provider MAY choose to check if a stored credential is still valid by inspecting any stored metadata associated with the value. A host provider MAY also choose to further validate a retrieved stored credential by making a web request. However, it is NOT RECOMMENDED to make any request that is known to be -slow or that typically produces inconclusive valudation results. +slow or that typically produces inconclusive validation results. If a provider chooses to make a validation web request and that request fails or is inconclusive, it SHOULD assume the credential is still valid and return it @@ -184,7 +184,7 @@ attempt first. Host providers are RECOMMENDED to attempt authentication mechanisms that do not require user interaction if possible. If there are multiple authentication mechanisms that could be equally considered "best" they MAY prompt the user -to make a selection. Host providers MAY wish to rememeber such a selection for +to make a selection. Host providers MAY wish to remember such a selection for future use, however they MUST make it clear how to clear this stored selection to the user. @@ -249,7 +249,7 @@ provider implementors. This base class implements most required methods of the `IHostProvider` interface with common credential recall and storage behaviour. The `GetCredentialAsync`, `StoreCredentialAsync`, and `EraseCredentialAsync` -methods are implemented as `virtual` meaning they MAY be overriden by derived +methods are implemented as `virtual` meaning they MAY be overridden by derived classes to customise the behaviour of those operations. It is NOT RECOMMENDED to derive from the `HostProvider` base class if the implementor must override most of the methods as implemented - implementors SHOULD implement the @@ -300,7 +300,7 @@ features such as native APIs and native graphical user interfaces, in order to offer a better authentication experience. Host providers MUST function without the presence of a helper, even if that -function is to fail gracefully with a user friendly error message, including +function is to fail gracefully with a user-friendly error message, including a remedy to correct their installation. Host providers SHOULD always offer a terminal/TTY or text-based authentication mechanism alongside any graphical interface provided by a helper. @@ -312,7 +312,7 @@ etc. Communications between the main and helper processes MAY use any IPC mechanism available. It is RECOMMENDED implementors use standard input/output streams or -file descriptors to send and recieve data as this is consistent with how Git and +file descriptors to send and receive data as this is consistent with how Git and GCM Core communicate. UNIX sockets or Windows Named Pipes MAY also be used when an ongoing back-and-forth communication is required. diff --git a/docs/netconfig.md b/docs/netconfig.md index c430e9999..b2e969890 100644 --- a/docs/netconfig.md +++ b/docs/netconfig.md @@ -6,7 +6,7 @@ Git Credential Manager Core's network and HTTP(S) behavior can be configured in If your computer sits behind a network firewall that requires the use of a proxy server to reach repository remotes or the wider Internet, there are various methods for configuring GCM to use a proxy. -The simplist way to configure a proxy for _all_ HTTP(S) remotes is to [use the standard Git HTTP(S) proxy setting `http.proxy`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy). +The simplest way to configure a proxy for _all_ HTTP(S) remotes is to [use the standard Git HTTP(S) proxy setting `http.proxy`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy). For example to configure a proxy for all remotes for the current user: @@ -57,7 +57,7 @@ GCM Core supports other ways of configuring a proxy for convenience and compatib ## TLS Verification -If you are using self-signed TLS (SSL) certificates with a self-hosted host provider such as GitHub Enteprise Server or Azure DevOps Server (previously TFS), you may see the following error message when attempting to connect using Git and/or GCM: +If you are using self-signed TLS (SSL) certificates with a self-hosted host provider such as GitHub Enterprise Server or Azure DevOps Server (previously TFS), you may see the following error message when attempting to connect using Git and/or GCM: ```shell $ git clone https://ghe.example.com/john.doe/myrepo @@ -66,7 +66,7 @@ fatal: The remote certificate is invalid according to the validation procedure. The **recommended and safest option** is to acquire a TLS certificate signed by a public trusted certificate authority (CA). There are multiple public CAs; here is a non-exhaustive list to consider: [Let's Encrypt](https://letsencrypt.org/), [Comodo](https://www.comodoca.com/), [Digicert](https://www.digicert.com/), [GoDaddy](https://www.godaddy.com/web-security/ssl-certificate), [GlobalSign](https://www.globalsign.com/en/ssl/). -If it is not possible to **obtain a TLS certifiate from a trusted 3rd party** then you should try to add the _specific_ self-signed certificate or one of the CA certificates in the verification chain to your operating system's trusted certificate store ([macOS](https://support.apple.com/en-gb/guide/keychain-access/kyca2431/mac), [Windows](https://blogs.technet.microsoft.com/sbs/2008/05/08/installing-a-self-signed-certificate-as-a-trusted-root-ca-in-windows-vista/)). +If it is not possible to **obtain a TLS certificate from a trusted 3rd party** then you should try to add the _specific_ self-signed certificate or one of the CA certificates in the verification chain to your operating system's trusted certificate store ([macOS](https://support.apple.com/en-gb/guide/keychain-access/kyca2431/mac), [Windows](https://blogs.technet.microsoft.com/sbs/2008/05/08/installing-a-self-signed-certificate-as-a-trusted-root-ca-in-windows-vista/)). If you are _unable_ to either **obtain a trusted certificate**, or trust the self-signed certificate you can disable certificate verification in Git and GCM. @@ -75,11 +75,11 @@ If you are _unable_ to either **obtain a trusted certificate**, or trust the sel Disabling verification of TLS (SSL) certificates removes protection against a [man-in-the-middle (MITM) attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -Only disable certificate verification if you are sure you need to, are aware of all of the risks, and are unable to trust specific self-signed certificates (as described above). +Only disable certificate verification if you are sure you need to, are aware of all the risks, and are unable to trust specific self-signed certificates (as described above). --- -The [environment variable `GIT_SSL_NO_VERIFY`](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_networking) and [Git configuration option `http.sslVerify`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslVerify) can be used to control TLS (SSL) certifcate verification. +The [environment variable `GIT_SSL_NO_VERIFY`](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_networking) and [Git configuration option `http.sslVerify`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslVerify) can be used to control TLS (SSL) certificate verification. To disable verification for a specific remote (for example ):