Secure Git credential storage for Windows with support for Visual Studio Team Services, GitHub, and Bitbucket multi-factor authentication.
View the Project on GitHub microsoft/Git-Credential-Manager-for-Windows
Developing for GCM and/or Askpass requires Visual Studio 2017 or newer, any version (including the free Community Edition).
The easiest way to get started is to:
Once the GCM starts you’ll be presented with an unsatisfying console window. This is because the GCM expects to be launched by Git, not directly. However, it is easy to play the role of Git. The GCM expects Git to supply at least two pieces of information: the protocol being use and the host name for which the current operation is happening.
An example of faking Git request for GitHub credentials:
protocol=https
host=github.com
Notice the blank last line. That empty line is how Git and the GCM notify the other side that they’re done sending data. Until an empty line is sent to the GCM, it’ll keep attempting to read from standard input.
Once the blank line is fed to the GCM it’ll “do its thing”.
Ideally, you can watch it work, so that you can learn how it works and then improve it.
To do so, place a break point in the Main method of the ‘Program.cs’ file.
Doing so will allow you to “break in” when the execution pointer reaches your break point.
You’ll notice that the GCM doesn’t read from standard input immediately; instead it does some setup work to determine what it expected of it and then only reads from standard input if it is expected to.
In the case of “git credential-manager get”, the Main method will call the Program.Get method, which in turn will allocate a new OperationArguments object and initialize it with the process’ standard input pipe.
This is when standard input will be consumed by the GCM.
Program.LoadOperationArguments method is where the GCM scans, parses, and consumes environmental and configuration setting values.Program.QueryCredentials method is where the “action” happens.OperationArguments class is where the GCM consumes standard input and keeps internal state.Changes to the installer (GCMW-{version}.exe) requires Inno Setup Compiler 5.5.9 or later to compile.
Additionally, the IDP plugin for Inno Setup is also required.
The setup compiler pulls content from the “Deploy/” folder, therefore a completed Debug or Release build needs to have been completed prior to running the setup compiler. Content in the “Deploy/” folder will be used in the setup compilation.
The Microsoft.Alm.Authentication NuGet package is automatically created when the Microsoft.Alm.Authentication project is built. The generated “.nupkg” files can be found in the “Debug/” or “Release/” (depending on your build target) under “Microsoft.Alm.Authentication/bin/”. Both the binary and symbol packages are automatically created.
Updates to the NuGet package stream are reserved for officially built binaries.
Only Microsoft can sign binaries with the Microsoft certificate. Therefore, while anyone can build and use their own binaries from the GCM source code, only officially releases binaries will be signed by Microsoft.
The documentation is formatted using markdown and generated using Pandoc.
To enable logging, use the following:
git config --global credential.writelog true
Log files will be written to the repository’s local .git/ folder.
Additionally, the GCM outputs GIT_TRACE compatible logging. To use the GIT_TRACE mechanism you can either:
SET GCM_TRACE=1; this will cause the GCM to log directly to the console.SET GIT_TRACE=1; now Git will log directly to the console.Or
setx GCM_TRACE %UserProfile%\git.log; this will cause the GCM to log to a file located at “%UserProfile%\git.log”.setx GIT_TRACE %UserProfile%\git.log; now Git will log to the file located at “%UserProfile%\git.log”.setx GCM_TRACE "" or GIT_TRACE "".Note: The path for logging is arbitrary and both GCM and Git will create/append the file, however neither Git nor the GCM will create any folders; therefore it is up to the user to specify a folder that exists. Additionally, if the specified path contains spaces, be sure to wrap the path in double-quote characters (example: “%UserProfile%\my git.log”). Finally, inaccessible paths could cause either Git or the GCM to fail unexpectedly, therefor avoid specifying paths which the user’s account does not have access to; for example paths like “%ProgramFiles%\Git\logs\trace.log” are not recommended because only elevated processes can write to “%ProgramFiles%”.
Debug build of the GCM will perform extended logging to the console, which is convenient for debugging purposes bug too noisy for day-to-day usage.
There are many ways to contribute.
For code contributions, you will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you grant us permission to use the submitted change according to the terms of the project’s license, and that the work being submitted is under the appropriate copyright.
Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.microsoft.com to sign digitally. Alternatively, download the agreement Microsoft Contribution License Agreement.pdf, sign, scan, and email it back to cla@microsoft.com. Be sure to include your GitHub user name along with the agreement. Once we have received the signed CLA, we’ll review the request.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project uses the MIT License.