Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix some typos/errors in documentation #158

Merged
merged 1 commit into from
Aug 7, 2020
Merged

Fix some typos/errors in documentation #158

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Directory.Build.props
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<PropertyGroup>
<!--
Set helpful property for detecting the current OS platform.
We can't use the build-in $(OS) because it returns 'Unix' on macOS when run under Mono.
We can't use the built-in $(OS) because it returns 'Unix' on macOS when run under Mono.
-->
<OSPlatform Condition="$([MSBuild]::IsOsPlatform('windows'))">windows</OSPlatform>
<OSPlatform Condition="$([MSBuild]::IsOsPlatform('osx'))">osx</OSPlatform>
Expand Down
12 changes: 6 additions & 6 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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)).

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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`.

Expand Down
4 changes: 2 additions & 2 deletions docs/environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`.

Expand Down
2 changes: 1 addition & 1 deletion docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
22 changes: 11 additions & 11 deletions docs/hostprovider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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".

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand Down
10 changes: 5 additions & 5 deletions docs/netconfig.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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 <https://example.com>):

Expand Down