Rename entry executable to drop "-core" suffix (#551)

Rename the main entry executable from `git-credential-manager-core(.exe)` to simply `git-credential-manager(.exe)`, now that the older GCM4W has been removed from the Git for Windows project as an option (and the GCMC project has been renamed). We do **not** rename the Debian package ID, nor the Homebrew Cask name yet as this will require more thought forr migration. To help with migration somewhat, create symlinks and shim/copy-executables for the original executable name "git-credential-manager-core(.exe)" for consumers who have not updated to the new version. We detect if the consumer is launching us via the "-core" symlink or executable shim by consulting the platform-native APIs to get the original "argv[0]". All of the .NET APIs sadly don't give us the real "argv[0]", so we need to use native APIs... If we detect use of the old name, print a warning that the user should update their configuration, and a help link for more information.
git-ecosystem · Oct 24, 2022 · 02204ac · 02204ac
2 parents 7047f48 + a47e1ce
commit 02204ac
Show file tree

Hide file tree

Showing 34 changed files with 440 additions and 83 deletions.
diff --git a/.github/ISSUE_TEMPLATE/auth-problem.md b/.github/ISSUE_TEMPLATE/auth-problem.md
@@ -8,7 +8,7 @@ assignees: ''
 
 **Which version of GCM are you using?**
 
-From a terminal, run `git credential-manager-core --version` and paste the output.
+From a terminal, run `git credential-manager --version` and paste the output.
 
 <!-- Ex:
 Git Credential Manager version 2.0.8-beta+e1f8492d04 (macOS, .NET Core 4.6.27129.04)

diff --git a/.github/ISSUE_TEMPLATE/experimental.md b/.github/ISSUE_TEMPLATE/experimental.md
@@ -8,7 +8,7 @@ assignees: ''
 
 **Which version of GCM are you using?**
 
-From a terminal, run `git credential-manager-core --version` and paste the output.
+From a terminal, run `git credential-manager --version` and paste the output.
 
 <!-- Ex:
 Git Credential Manager version 2.0.8-beta+e1f8492d04 (macOS, .NET Core 4.6.27129.04)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -443,17 +443,17 @@ jobs:
         component:
           - os: ubuntu-latest
             artifact: linux-sign
-            command: git-credential-manager-core
+            command: git-credential-manager
           - os: macos-latest
             artifact: osx-x64-sign
-            command: git-credential-manager-core
+            command: git-credential-manager
           - os: windows-latest
             artifact: win-sign
             # Even when a standalone GCM version is installed, GitHub actions
             # runners still only recognize the version bundled with Git for
             # Windows due to its placement on the PATH. For this reason, we use
             # the full path to our installation to validate the Windows version.
-            command: "$PROGRAMFILES (x86)/Git Credential Manager/git-credential-manager-core.exe"
+            command: "$PROGRAMFILES (x86)/Git Credential Manager/git-credential-manager.exe"
     runs-on: ${{ matrix.component.os }}
     needs: [ osx-sign, win-sign, linux-sign ]
     steps:

diff --git a/.github/workflows/validate-install-from-source.yml b/.github/workflows/validate-install-from-source.yml
@@ -32,4 +32,4 @@ jobs:
           fi
 
           sh "${GITHUB_WORKSPACE}/src/linux/Packaging.Linux/install-from-source.sh" -y
-          git-credential-manager-core --help || exit 1
+          git-credential-manager --help || exit 1
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -10,7 +10,7 @@
             "request": "launch",
             "preLaunchTask": "build",
             // If you have changed target frameworks, make sure to update the program path.
-            "program": "${workspaceFolder}/out/shared/Git-Credential-Manager/bin/Debug/net6.0/git-credential-manager-core.dll",
+            "program": "${workspaceFolder}/out/shared/Git-Credential-Manager/bin/Debug/net6.0/git-credential-manager.dll",
             "args": ["get"],
             "cwd": "${workspaceFolder}/out/shared/Git-Credential-Manager",
             "console": "integratedTerminal",
@@ -22,7 +22,7 @@
             "request": "launch",
             "preLaunchTask": "build",
             // If you have changed target frameworks, make sure to update the program path.
-            "program": "${workspaceFolder}/out/shared/Git-Credential-Manager/bin/Debug/net6.0/git-credential-manager-core.dll",
+            "program": "${workspaceFolder}/out/shared/Git-Credential-Manager/bin/Debug/net6.0/git-credential-manager.dll",
             "args": ["store"],
             "cwd": "${workspaceFolder}/out/shared/Git-Credential-Manager",
             "console": "integratedTerminal",

diff --git a/README.md b/README.md
@@ -116,7 +116,7 @@ Download the latest [.deb package][latest-release], and run the following:
 
 ```shell
 sudo dpkg -i <path-to-package>
-git-credential-manager-core configure
+git-credential-manager configure
 ```
 
 **Note:** Although packages were previously offered on certain
@@ -127,7 +127,7 @@ Debian package using the above instructions instead.
 To uninstall:
 
 ```shell
-git-credential-manager-core unconfigure
+git-credential-manager unconfigure
 sudo dpkg -r gcmcore
 ```
 
@@ -139,14 +139,14 @@ Download the latest [tarball][latest-release], and run the following:
 
 ```shell
 tar -xvf <path-to-tarball> -C /usr/local/bin
-git-credential-manager-core configure
+git-credential-manager configure
 ```
 
 To uninstall:
 
 ```shell
-git-credential-manager-core unconfigure
-rm $(command -v git-credential-manager-core)
+git-credential-manager unconfigure
+rm $(command -v git-credential-manager)
 ```
 
 #### Option 2: Install from source helper script

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -56,7 +56,7 @@ library (C#). The library targets .NET Standard as well as .NET Framework.
 
 The entry-point for GCM can be found in the `Git-Credential-Manager`
 project, a console application that targets both .NET and .NET Framework.
-This project emits the `git-credential-manager-core(.exe)` executable, and
+This project emits the `git-credential-manager(.exe)` executable, and
 contains very little code - registration of all supported host providers and
 running the `Application` object found in `Core`.
 

diff --git a/docs/azrepos-users-and-tokens.md b/docs/azrepos-users-and-tokens.md
@@ -70,7 +70,7 @@ In advanced scenarios (such as using multiple accounts) you can interact with
 and manage remembered user accounts using the 'azure-repos' provider command:
 
 ```shell
-git-credential-manager-core azure-repos [ list | bind | unbind | ... ] <options>
+git-credential-manager azure-repos [ list | bind | unbind | ... ] <options>
 ```
 
 ##### Listing remembered accounts
@@ -79,7 +79,7 @@ You can list all bound user accounts by Git Credential Manager for each Azure
 DevOps organization using the `list` command:
 
 ```shell
-$ git-credential-manager-core azure-repos list
+$ git-credential-manager azure-repos list
 contoso:
   (global) -> [email protected]
 fabrikam:
@@ -105,7 +105,7 @@ the `.git/config` file. If there are local bindings in a repository you can show
 them with the `list` command:
 
 ```shell
-~/myrepo$ git-credential-manager-core azure-repos list
+~/myrepo$ git-credential-manager azure-repos list
 contoso:
   (global) -> [email protected]
   (local)  -> [email protected]
@@ -118,7 +118,7 @@ To create a local binding, use the `bind` command with the `--local` option when
 inside a repository:
 
 ```shell
-~/myrepo$ git-credential-manager-core azure-repos bind --local contoso [email protected]
+~/myrepo$ git-credential-manager azure-repos bind --local contoso [email protected]
 ```
 
 ```diff
@@ -132,7 +132,7 @@ inside a repository:
 To have Git Credential Manager forget a user account, use the `unbind` command:
 
 ```shell
-git-credential-manager-core azure-repos unbind fabrikam
+git-credential-manager azure-repos unbind fabrikam
 ```
 
 ```diff
@@ -151,7 +151,7 @@ To forget or remove a local binding, within the repository run the `unbind`
 command with the `--local` option:
 
 ```shell
-~/myrepo$ git-credential-manager-core azure-repos unbind --local contoso
+~/myrepo$ git-credential-manager azure-repos unbind --local contoso
 ```
 
 ```diff
@@ -170,7 +170,7 @@ To show which accounts are being used for each Git remote in a repository use
 the `list` command with the `--show-remotes` option:
 
 ```shell
-~/myrepo$ git-credential-manager-core azure-repos list --show-remotes
+~/myrepo$ git-credential-manager azure-repos list --show-remotes
 contoso:
   (global) -> [email protected]
   origin:
@@ -208,7 +208,7 @@ The `list --show-remotes` command will show the user account specified in the
 remote URL:
 
 ```shell
-~/myrepo$ git-credential-manager-core azure-repos list --show-remotes
+~/myrepo$ git-credential-manager azure-repos list --show-remotes
 contoso:
   (global) -> [email protected]
   origin:

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -20,7 +20,7 @@ Additionally, GCM respects several GCM-specific [environment variables][envars]
 also configure [default values][enterprise-config] for many settings used by GCM.
 
 GCM will only be used by Git if it is installed and configured. Use
-`git config --global credential.helper manager-core` to assign GCM as your
+`git config --global credential.helper manager` to assign GCM as your
 credential helper. Use `git config credential.helper` to see the current
 configuration.
 

diff --git a/docs/development.md b/docs/development.md
@@ -105,7 +105,7 @@ error, or to an absolute file path to write trace information to a file.
 For example:
 
 ```shell
-$ GCM_TRACE=1 git-credential-manager-core version
+$ GCM_TRACE=1 git-credential-manager version
 > 18:47:56.526712 ...er/Application.cs:69 trace: [RunInternalAsync] Git Credential Manager version 2.0.124-beta+e1ebbe1517 (macOS, .NET 5.0) 'version'
 > Git Credential Manager version 2.0.124-beta+e1ebbe1517 (macOS, .NET 5.0)
 ```

diff --git a/docs/img/gcmcore-rename.png b/docs/img/gcmcore-rename.png
diff --git a/docs/linux-fromsrc-uninstall.md b/docs/linux-fromsrc-uninstall.md
@@ -25,8 +25,8 @@ pre-existing clone or the directory from which you ran the install from source
 script.
 
 ```console
-git-credential-manager-core unconfigure &&
-sudo rm $(command -v git-credential-manager-core) &&
+git-credential-manager unconfigure &&
+sudo rm $(command -v git-credential-manager) &&
 sudo rm -rf /usr/local/share/gcm-core &&
 sudo rm -rf ~/git-credential-manager &&
 sudo rm ~/install-from-source.sh

diff --git a/docs/rename.md b/docs/rename.md
@@ -0,0 +1,166 @@
+# Git Credential Manager Rename
+
+In November 2021, _"Git Credential Manager Core"_ was [renamed][rename-pr] to
+simply _"Git Credential Manager"_, dropping the "Core" moniker. We announced the
+new name in a [GitHub blog post][rename-blog], along with the new home for the
+project in it's own [organization][gcm-org].
+
+![Git Credential Manager Core renamed](img/gcmcore-rename.png)
+
+At the time, the actual exectuable name was not updated and continued to be
+`git-credential-manager-core`. As of [VERSION][rename-ver], the executable has
+been renamed to `git-credential-manager`, matching the new project name.
+
+## Rename transition
+
+If you continue to use the `git-credential-manager-core` executable name you may
+see warning messages like below:
+
+```console
+warning: git-credential-manager-core was renamed to git-credential-manager
+warning: see https://aka.ms/gcm/rename for more information
+```
+
+Since the executable was renamed in VERSION, GCM has also included symlinks
+using the old name in order to ensure no one's setups would immediately break.
+
+These links will remain until _two_ major Git versions are released after GCM
+VERSION, _**at which point the symlinks will no longer be included**_.
+
+It is recommended to update your Git configuration to use the new executable
+name as soon as possible to prevent any issues in the future.
+
+## How to update
+
+### Git for Windows
+
+If you are using GCM bundled with Git for Windows (recommended), you should make
+sure you have updated to at least version WINGIT_VERSION.
+
+[Download the latest Git for Windows ⬇️][git-windows]
+
+### Windows standalone installer
+
+If you are using GCM installed either by the user (`gcmuser-*.exe`) or system
+(`gcm-*.exe`) installers on Windows, you should uninstall the current version
+first and then download and install the [latest version][gcm-latest].
+
+Uninstall instructions for your Windows version can be found
+[here][win-standalone-instr].
+
+### macOS Homebrew
+
+> **Note:** As of October 2022 the old `git-credential-manager-core` cask name
+> is still used. In the future we plan to rename the package to drop the `-core`
+> suffix.
+
+If you use Homebrew to install GCM on macOS you should use `brew upgrade` to
+install the latest version.
+
+```sh
+brew upgrade git-credential-manager-core
+```
+
+### macOS package
+
+If you use the .pkg file to install GCM on macOS, you should first uninstall the
+current version, and then install the [latest package][gcm-latest].
+
+```sh
+sudo /usr/local/share/gcm-core/uninstall.sh
+installer -pkg <path-to-new-package> -target /
+```
+
+### Linux Debian package
+
+If you use the .deb Debian package to install GCM on Linux, you should first
+`unconfigure` the current version, uninstall the package, and then install and
+`configure` the [latest version][gcm-latest].
+
+```sh
+git-credential-manager-core unconfigure
+sudo dpkg -r gcmcore
+sudo dpkg -i <path-to-new-package>
+git-credential-manager configure
+```
+
+### Linux tarball
+
+If you are using the pre-built GCM binaries on Linux from our tarball, you
+should first `unconfigure` the current version before extracting the [latest
+binaries][gcm-latest].
+
+```sh
+git-credential-manager-core unconfigure
+rm $(command -v git-credential-manager-core)
+tar -xvf <path-to-new-tarball> -C /usr/local/bin
+git-credential-manager configure
+```
+
+### Troubleshooting
+
+If after updating your GCM installations if you are still seeing the
+[warning][warnings] messages you can try manually editing your Git configuration
+to point to the correct GCM executable name.
+
+Start by listing all Git configuration for `credential.helper`, including which
+files the particular config entries are located in, using the following command:
+
+```sh
+git config --show-origin --get-all credential.helper
+```
+
+On Mac or Linux you should see something like this:
+
+<!-- markdownlint-disable MD010 -->
+```shell-session
+$ git config --show-origin --get-all credential.helper
+file:/opt/homebrew/etc/gitconfig	credential.helper=osxkeychain
+file:/Users/jdoe/.gitconfig	credential.helper=
+file:/Users/jdoe/.gitconfig	credential.helper=/usr/local/share/gcm-core/git-credential-manager-core
+```
+
+On Windows you should see something like this:
+
+```shell-session
+> git config --show-origin --get-all credential.helper
+file:C:/Program Files/Git/etc/gitconfig	credential.helper=manager-core
+```
+<!-- markdownlint-enable MD010 -->
+
+Look out for entries that include `git-credential-manager-core` or
+`manager-core`; these should be replaced and updated to `git-credential-manager`
+or `manager` respectively.
+
+> **Note:** When updating the Git configuration file in your home directory
+> (`$HOME/.gitconfig` or `%USERPROFILE\.gitconfig%`) you should ensure there are
+> is an additional blank entry for `credential.helper` before the GCM entry.
+>
+> **Mac/Linux**
+>
+> ```ini
+> [credential]
+>     helper =
+>     helper = /usr/local/share/gcm-core/git-credential-manager
+> ```
+>
+> **Windows**
+>
+> ```ini
+> [credential]
+>     helper =
+>     helper = C:/Program\\ Files\\ \\(x86\\)/Git\\ Credential\\ Manager/git-credential-manager.exe
+> ```
+>
+> The blank entry is important as it makes sure GCM is the only credential
+> helper that is configured, and overrides any helpers configured at the system/
+> machine-wide level.
+
+[rename-pr]: https://github.com/GitCredentialManager/git-credential-manager/pull/541
+[rename-blog]: https://github.blog/2022-04-07-git-credential-manager-authentication-for-everyone/#universal-git-authentication
+[gcm-org]: https://github.com/GitCredentialManager
+[rename-ver]: https://github.com/GitCredentialManager/git-credential-manager/releases
+[git-windows]: https://git-scm.com/download/win
+[gcm-latest]: https://aka.ms/gcm/latest
+[warnings]: #rename-transition
+[win-standalone-instr]: ../README.md#standalone-installation
diff --git a/docs/usage.md b/docs/usage.md
@@ -9,7 +9,7 @@ Assuming GCM has been installed, use your favorite terminal to execute the
 following commands to interact directly with GCM.
 
 ```shell
-git credential-manager-core [<command> [<args>]]
+git credential-manager [<command> [<args>]]
 ```
 
 ## Commands