Switch to reference style links

git-ecosystem · May 2, 2022 · 9dfa207 · 9dfa207
1 parent 86714ff
commit 9dfa207
Show file tree

Hide file tree

Showing 12 changed files with 279 additions and 146 deletions.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -73,6 +73,6 @@ available at [Contributor Covenant Code of Conduct][cc-coc].
 For answers to common questions about this code of conduct, see the
 [Contributor Covenant FAQ][cc-faq]
 
-[cc-homepage]: https://www.contributor-covenant.org
 [cc-coc]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
 [cc-faq]: https://www.contributor-covenant.org/faq
+[cc-homepage]: https://www.contributor-covenant.org
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,13 +1,8 @@
 # Contributing
 
-[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues
-[fork]: https://github.com/GitCredentialManager/git-credential-manager/fork
-[pr]: https://github.com/GitCredentialManager/git-credential-manager/compare
-[code-of-conduct]: CODE_OF_CONDUCT.md
-
 Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
 
-Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
+Contributions to this project are [released][contribute-under-repo-license] to the public under the [project's open source license][license].
 
 Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms.
 
@@ -29,18 +24,29 @@ This helps us coordinate and reduce duplication.
     - `GitHub.UI.Avalonia`
     - `Atlassian.Bitbucket.UI.Windows`
     - `GitHub.UI.Windows`
-1. Push to your fork and [submit a pull request][pr]
+1. Push to your fork and [submit a pull request][compare]
 1. Pat your self on the back and wait for your pull request to be reviewed and merged.
 
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 
 - Match existing code style.
 - Write tests.
 - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
-- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+- Write a [good commit message][commit-messages].
 
 ## Resources
 
-- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
-- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
-- [GitHub Help](https://help.github.com)
+- [How to Contribute to Open Source][how-to-contribute]
+- [Using Pull Requests][prs]
+- [GitHub Help][github-help]
+
+[code-of-conduct]: CODE_OF_CONDUCT.md
+[commit-messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[compare]: https://github.com/GitCredentialManager/git-credential-manager/compare
+[contribute-under-repo-license]: https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license
+[fork]: https://github.com/GitCredentialManager/git-credential-manager/fork
+[github-help]: https://help.github.com
+[how-to-contribute]: https://opensource.guide/how-to-contribute/
+[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues
+[license]: LICENSE
+[prs]: https://help.github.com/articles/about-pull-requests/
diff --git a/README.md b/README.md
@@ -1,27 +1,27 @@
 # Git Credential Manager
 
-[![Build Status](https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml)
+[![Build Status][build-status-badge]][workflow-status]
 
 ---
 
-[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) is a secure Git credential helper built on [.NET](https://dotnet.microsoft.com) that runs on Windows, macOS, and Linux.
+[Git Credential Manager][gcm] (GCM) is a secure Git credential helper built on [.NET][] that runs on Windows, macOS, and Linux.
 
-Compared to Git's [built-in credential helpers]((https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage)) (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM provides multi-factor authentication support for [Azure DevOps](https://dev.azure.com/), Azure DevOps Server (formerly Team Foundation Server), GitHub, Bitbucket, and GitLab.
+Compared to Git's [built-in credential helpers][git-tools-credential-storage] (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM provides multi-factor authentication support for [Azure DevOps][], Azure DevOps Server (formerly Team Foundation Server), GitHub, and Bitbucket.
 
-Git Credential Manager (GCM) replaces the .NET Framework-based [Git Credential Manager for Windows](https://github.com/microsoft/Git-Credential-Manager-for-Windows) (GCM), and the Java-based [Git Credential Manager for Mac and Linux](https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux) (Java GCM), providing a consistent authentication experience across all platforms.
+Git Credential Manager (GCM) replaces the .NET Framework-based [Git Credential Manager for Windows][gcm-for-windows] (GCM), and the Java-based [Git Credential Manager for Mac and Linux][gcm-for-mac-and-linux] (Java GCM), providing a consistent authentication experience across all platforms.
 
 ## Current status
 
 Git Credential Manager is currently available for Windows, macOS, and Linux\*. GCM only works with HTTP(S) remotes; you can still use Git with SSH:
 
-- [Azure DevOps SSH](https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops)
-- [GitHub SSH](https://help.github.com/en/articles/connecting-to-github-with-ssh)
-- [Bitbucket SSH](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html)
+- [Azure DevOps SSH][]
+- [GitHub SSH][]
+- [Bitbucket SSH][]
 
 Feature|Windows|macOS|Linux
 -|:-:|:-:|:-:
 Installer/uninstaller|&#10003;|&#10003;|&#10003;\*
-Secure platform credential storage|&#10003; [(see more)](docs/credstores.md)|&#10003; [(see more)](docs/credstores.md)|&#10003; [(see more)](docs/credstores.md)
+Secure platform credential storage|&#10003; [(see more)][gcm-credstores]|&#10003; [(see more)][gcm-credstores]|&#10003; [(see more)][gcm-credstores]
 Multi-factor authentication support for Azure DevOps|&#10003;|&#10003;|&#10003;
 Two-factor authentication support for GitHub|&#10003;|&#10003;|&#10003;
 Two-factor authentication support for Bitbucket|&#10003;|&#10003;|&#10003;
@@ -75,7 +75,7 @@ brew uninstall --cask git-credential-manager-core
 
 ### macOS Package
 
-We also provide a [.pkg installer](https://github.com/GitCredentialManager/git-credential-manager/releases/latest) with each release. To install, double-click the installation package and follow the instructions presented.
+We also provide a [.pkg installer][latest-release] with each release. To install, double-click the installation package and follow the instructions presented.
 
 #### Uninstall
 
@@ -121,15 +121,15 @@ run the following:
 
 #### Ubuntu/Debian distributions
 
-Download the latest [.deb package](https://github.com/GitCredentialManager/git-credential-manager/releases/latest), and run the following:
+Download the latest [.deb package][latest-release], and run the following:
 
 ```shell
 sudo dpkg -i <path-to-package>
 git-credential-manager-core configure
 ```
 
 **Note:** Although packages were previously offered on certain
-[Microsoft Ubuntu package feeds](https://packages.microsoft.com/repos/),
+[Microsoft Ubuntu package feeds][ms-package-repos],
 GCM no longer publishes to these repositories. Please install the
 Debian package using the above instructions instead.
 
@@ -142,7 +142,7 @@ sudo dpkg -r gcmcore
 
 #### Other distributions
 
-Download the latest [tarball](https://github.com/GitCredentialManager/git-credential-manager/releases/latest), and run the following:
+Download the latest [tarball][latest-release], and run the following:
 
 ```shell
 tar -xvf <path-to-tarball> -C /usr/local/bin
@@ -156,19 +156,19 @@ git-credential-manager-core unconfigure
 rm $(command -v git-credential-manager-core)
 ```
 
-**Note:** all Linux distributions [require additional configuration](https://aka.ms/gcm/credstores) to use GCM.
+**Note:** all Linux distributions [require additional configuration][gcm-credstores] to use GCM.
 
 ---
 
 ### Windows
 
-GCM is included with [Git for Windows](https://gitforwindows.org/), and the latest version is included in each new Git for Windows release. This is the preferred way to install GCM on Windows. During installation you will be asked to select a credential helper, with GCM being set as the default.
+GCM is included with [Git for Windows][], and the latest version is included in each new Git for Windows release. This is the preferred way to install GCM on Windows. During installation you will be asked to select a credential helper, with GCM being set as the default.
 
-![image](https://user-images.githubusercontent.com/5658207/140082529-1ac133c1-0922-4a24-af03-067e27b3988b.png)
+![image][git-for-windows-screenshot]
 
 #### Standalone installation
 
-You can also download the [latest installer](https://github.com/GitCredentialManager/git-credential-manager/releases/latest) for Windows to install GCM standalone.
+You can also download the [latest installer][latest-release] for Windows to install GCM standalone.
 
 **:warning: Important :warning:**
 
@@ -197,10 +197,10 @@ To uninstall, open Control Panel and navigate to the Programs and Features scree
 #### Windows Subsystem for Linux (WSL)
 
 Git Credential Manager can be used with the [Windows Subsystem for Linux
-(WSL)](https://aka.ms/wsl) to enable secure authentication of your remote Git
+(WSL)][ms-wsl] to enable secure authentication of your remote Git
 repositories from inside of WSL.
 
-[Please see the GCM on WSL docs](docs/wsl.md) for more information.
+[Please see the GCM on WSL docs][gcm-wsl] for more information.
 
 ## Supported Git versions
 
@@ -215,50 +215,89 @@ Git that are not compatible.
 - Git 2.26.2
 
   This version of Git introduced a breaking change with parsing credential
-  configuration that GCM relies on. This issue was fixed in commit [`12294990`](https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340)
+  configuration that GCM relies on. This issue was fixed in commit [`12294990`][gcm-commit-12294990]
   of the Git project, and released in Git 2.27.0.
 
 ## How to use
 
 Once it's installed and configured, Git Credential Manager is called implicitly by Git.
 You don't have to do anything special, and GCM isn't intended to be called directly by the user.
-For example, when pushing (`git push`) to [Azure DevOps](https://dev.azure.com), [Bitbucket](https://bitbucket.org), or [GitHub](https://github.com), a window will automatically open and walk you through the sign-in process.
+For example, when pushing (`git push`) to [Azure DevOps][], [Bitbucket][], or [GitHub][], a window will automatically open and walk you through the sign-in process.
 (This process will look slightly different for each Git host, and even in some cases, whether you've connected to an on-premises or cloud-hosted Git host.)
 Later Git commands in the same repository will re-use existing credentials or tokens that GCM has stored for as long as they're valid.
 
-Read full command line usage [here](docs/usage.md).
+Read full command line usage [here][gcm-usage].
 
 ### Configuring a proxy
 
-See detailed information [here](https://aka.ms/gcm/httpproxy).
+See detailed information [here][gcm-http-proxy].
 
 ## Additional Resources
 
-- [Frequently asked questions](docs/faq.md)
-- [Development and debugging](docs/development.md)
-- [Command-line usage](docs/usage.md)
-- [Configuration options](docs/configuration.md)
-- [Environment variables](docs/environment.md)
-- [Enterprise configuration](docs/enterprise-config.md)
-- [Network and HTTP configuration](docs/netconfig.md)
-- [Credential stores](docs/credstores.md)
-- [Architectural overview](docs/architecture.md)
-- [Host provider specification](docs/hostprovider.md)
-- [Azure Repos OAuth tokens](docs/azrepos-users-and-tokens.md)
-- [GitLab support](docs/gitlab.md)
+- [Frequently asked questions][gcm-faq]
+- [Development and debugging][gcm-dev]
+- [Command-line usage][gcm-usage]
+- [Configuration options][gcm-config]
+- [Environment variables][gcm-env]
+- [Enterprise configuration][gcm-enterprise-config]
+- [Network and HTTP configuration][gcm-net-config]
+- [Credential stores][gcm-credstores]
+- [Architectural overview][gcm-arch]
+- [Host provider specification][gcm-host-provider]
+- [Azure Repos OAuth tokens][gcm-azure-tokens]
+- [GitLab support][gcm-gitlab]
 
 ## Experimental Features
 
-- [Windows broker (experimental)](docs/windows-broker.md)
+- [Windows broker (experimental)][gcm-windows-broker]
 
 ## Contributing
 
 This project welcomes contributions and suggestions.
-See the [contributing guide](CONTRIBUTING.md) to get started.
+See the [contributing guide][gcm-contributing] to get started.
 
-This project follows [GitHub's Open Source Code of Conduct](CODE_OF_CONDUCT.md).
+This project follows [GitHub's Open Source Code of Conduct][gcm-coc].
 
 ## License
 
-We're [MIT](LICENSE) licensed.
-When using GitHub logos, please be sure to follow the [GitHub logo guidelines](https://github.com/logos).
+We're [MIT][gcm-license] licensed.
+When using GitHub logos, please be sure to follow the [GitHub logo guidelines][github-logos].
+
+[Azure DevOps]: https://dev.azure.com/
+[Azure DevOps SSH]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops
+[Bitbucket]: https://bitbucket.org
+[Bitbucket SSH]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html
+[build-status-badge]: https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg
+[.NET]: https://dotnet.microsoft.com
+[gcm]: https://github.com/GitCredentialManager/git-credential-manager
+[gcm-arch]: docs/architecture.md
+[gcm-azure-tokens]: docs/azrepos-users-and-tokens.md
+[gcm-coc]: CODE_OF_CONDUCT.md
+[gcm-commit-12294990]: https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340
+[gcm-config]: docs/configuration.md
+[gcm-contributing]: CONTRIBUTING.md
+[gcm-credstores]: docs/credstores.md
+[gcm-dev]: docs/development.md
+[gcm-enterprise-config]: docs/enterprise-config.md
+[gcm-env]: docs/environment.md
+[gcm-faq]: docs/faq.md
+[gcm-for-mac-and-linux]: https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux
+[gcm-for-windows]: https://github.com/microsoft/Git-Credential-Manager-for-Windows
+[gcm-gitlab]: docs/gitlab.md
+[gcm-host-provider]: docs/hostprovider.md
+[gcm-http-proxy]: docs/netconfig.md#http-proxy
+[gcm-license]: LICENSE
+[gcm-net-config]: docs/netconfig.md
+[gcm-usage]: docs/usage.md
+[gcm-windows-broker]: docs/windows-broker.md
+[gcm-wsl]: docs/wsl.md
+[Git for Windows]: https://gitforwindows.org/
+[git-for-windows-screenshot]: https://user-images.githubusercontent.com/5658207/140082529-1ac133c1-0922-4a24-af03-067e27b3988b.png
+[git-tools-credential-storage]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage
+[GitHub]: https://github.com
+[GitHub SSH]: https://help.github.com/en/articles/connecting-to-github-with-ssh
+[github-logos]: https://github.com/logos
+[latest-release]: https://github.com/GitCredentialManager/git-credential-manager/releases/latest
+[ms-package-repos]: https://packages.microsoft.com/repos/
+[ms-wsl]: https://aka.ms/wsl#
+[workflow-status]: https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,5 +1,7 @@
 # Security
 
-If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
+If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty][hackerone-github]
 
 Thanks for helping make GitHub products safe for everyone.
+
+[hackerone-github]: https://hackerone.com/github
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -44,16 +44,15 @@ library (C#). The library targets .NET Standard as well as .NET Framework.
 > **Note**
 >
 > The reason for also targeting .NET Framework directly is that the
-> `Microsoft.Identity.Client` ([MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet))
+> `Microsoft.Identity.Client` ([MSAL.NET][])
 > library requires a .NET Framework target to be able to show the embedded web
 > browser auth pop-up on Windows platforms.
 >
 > There are extension points that now exist in MSAL.NET meaning we can plug-in
 > our own browser pop-up handling code on .NET meaning both Windows and
 > Mac. We haven't yet gotten around to exploring this.
 >
-> See [this](https://github.com/GitCredentialManager/git-credential-manager/issues/113)
-> issue for more information.
+> See [GCM issue 113][] for more information.
 
 The entry-point for GCM can be found in the `Git-Credential-Manager`
 project, a console application that targets both .NET and .NET Framework.
@@ -80,9 +79,9 @@ helpers on Windows.
 
 ### Cross-platform UI
 
-We hope to be able to migrate the WPF/Windows only helpers to [Avalonia](https://avaloniaui.net/)
-in order to gain cross-platform graphical user interface support. See [this](https://github.com/GitCredentialManager/git-credential-manager/issues/136)
-issue for up-to-date progress on this effort.
+We hope to be able to migrate the WPF/Windows only helpers to [Avalonia][]
+in order to gain cross-platform graphical user interface support. See
+[GCM issue 136][] for up-to-date progress on this effort.
 
 ### Microsoft authentication
 
@@ -148,7 +147,7 @@ Git Credential Manager maintains a set of known commands including
 GCM also maintains a set of known, registered host providers that implement
 the `IHostProvider` interface. Providers register themselves by adding an
 instance of the provider to the `Application` object via the `RegisterProvider`
-method [in `Core.Program`](../src/shared/Git-Credential-Manager/Program.cs).
+method in [`Core.Program`][].
 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 presence of Windows Integrated Authentication (Kerberos, NTLM,
@@ -162,7 +161,7 @@ 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 overridden by the user via the
-[`credential.provider`](configuration.md#credentialprovider) or [`GCM_PROVIDER`](environment.md#GCM_PROVIDER)
+[`credential.provider`][] or [`GCM_PROVIDER`][]
 configuration and environment variable respectively (3)).
 
 The `Get|Store|EraseCommand`s call the corresponding
@@ -277,3 +276,11 @@ operation/authentication.
 The `ITrace` component can be found on the `ICommandContext` object or passed in
 directly to some constructors. Verbose and diagnostic information is be written
 to the trace object in most places of GCM.
+
+[avalonia]: https://avaloniaui.net/
+[`core.program`]: ../src/shared/Git-Credential-Manager/Program.cs
+[`credential.provider`]: configuration.md#credentialprovider
+[GCM issue 113]: https://github.com/GitCredentialManager/git-credential-manager/issues/113
+[GCM issue 136]: https://github.com/GitCredentialManager/git-credential-manager/issues/136
+[`GCM_PROVIDER`]: environment.md#GCM_PROVIDER
+[msal.net]: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet