# GitLink
**Repository Path**: gitsharp/GitLink
## Basic Information
- **Project Name**: GitLink
- **Description**: Making .NET open source accessible!
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-08-14
- **Last Updated**: 2024-08-14
## Categories & Tags
**Categories**: Uncategorized
**Tags**: Git
## README
GitLink
==========
[](https://ci.appveyor.com/project/gittools/gitlink/branch/develop)
[](https://gitter.im/GitTools/GitLink?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[][NuGetDownload]
[][NuGetDownload]
# Archive notice
This project is archived. The recommended approach is to use [SourceLink](https://github.com/dotnet/sourcelink), which is a great tool originally created by [@ctaggart](https://github.com/ctaggart) and has been adopted by the .NET Foundation.
# Description
GitLink lets users step through your code hosted on GitHub! **Help make .NET open source projects more accessible by enabling this for your .NET projects, it's just a single additional step in your build**. See the list of [projects using GitLink](#projects-using-gitlink).
--
**Important**
*GitLink* was formerly named *GitHubLink*. By adding support to more Git hosting services the name seemed not covering the whole package. The old GitHubLink packages on NuGet and Chocolatey will no longer be updated or maintained.
*Private git repositories* might be problematic. [More info](#source-stepping-returns-html).
--
GitLink makes symbol servers obsolete which saves you both time with uploading source files with symbols and the user no longer has to specify custom symbol servers (such as symbolsource.org).
The advantage of GitLink is that it is fully customized for Git. It also works with GitHub or BitBucket urls so it **does not require a local git repository to work**. This makes it perfectly usable in continuous integration servers such as Continua CI.
Updating all the pdb files is very fast. A solution with over 85 projects will be handled in less than 30 seconds.
When using GitLink, the user no longer has to specify symbol servers. The only requirement is to ensure the check the `Enable source server support` option in Visual Studio as shown below:
# How to use GitLink to enable source stepping on your own projects
## NuGet/MSBuild integration
The simplest way to use GitLink is to [install its NuGet package][NuGetDownload] into your project.
Install-Package GitLink
Once installed, it automatically integrates with MSBuild to add source download instructions to your PDB.
## Command line tool
If you want to install the tool on your (build) computer, the package is available via Chocolatey. To install, use the following command:
choco install gitlink
Using GitLink via the command line is very simple:
gitlink.exe
### Running for a custom raw content URL
When working with a content proxy or an alternative git VCS system that supports direct HTTP access to specific file revisions use the `-u` parameter with the custom raw content root URL
GitLink.exe -u https://raw.githubusercontent.com/catel/catel
The custom url will be used to fill in the following pattern `{customUrl}/{revision}/{relativeFilePath}` when generating the source mapping.
When working with a repository using uncommon URL you can use placeholders to specify where the filename and revision hash should be, use `-u` parameter with the custom URL
GitLink.exe -u "https://host/projects/catel/repos/catel/browse/{filename}?at={revision}&raw"
Or if you require URL encoded filename you can use `urlencoded_filename` token
GitLink.exe -u "http://host/api/v4/projects/42/repository/files/{urlencoded_filename}/raw?ref={revision}"
The custom url will be used to fill the placeholders with the relative file path and the revision hash.
### Git repository location
GitLink resolves the git repository based on the location of the pdb file. If the pdb file is located outside of the git repository, use the `-baseDir` parameter to point to the top-level directory of the repository.
### Native PDBs
Native PDBs (from C++ projects) are supported by using -a option:
GitLink.exe -a
All known C++ source files from your git depot will be indexed in the PDB.
### More options
There are many more parameters you can use. Display the usage doc with the following command line:
GitLink.exe -h
# How does it work
The SrcSrv tool (Srcsrv.dll) enables a client to retrieve the exact version of the source files that were used to build an application. Because the source code for a module can change between versions and over the course of years, it is important to look at the source code as it existed when the version of the module in question was built.
For more information, see the official documentation of SrcSrv.
GitLink creates a source index file and updates the PDB file so it will retrieve the files from the Git host file handler.
To do this, GitLink must be aware of the public URL from which the source files you compiled with can be retrieved.
GitLink.exe reads your compiler-generated PDB, which already contains full paths to your local source files.
It then searches for a git repo that contains those source files and looks up the commit that HEAD points to.
It also searches your remotes for a URL pattern that it recognizes (e.g. https://github.com/name/repo).
It combines the URL and the commit ID to create a unique URL for each source file of this exact version, and adds this information to your PDB.
When you share your PDB alongside your assembly, your users who debug with Source Server support enabled will automatically be able to step into your source code.
# Troubleshooting
## Source Stepping isn't working
* Visual Studio 2012 needs to run elevated in order to download the source server files
* Specify a value for Visual Studio -> Options -> Debugging -> Symbols -> `Cache Symbols in this directory`
## Source Stepping returns HTML
If your repository is private, you are likely seeing the logon HTML from your git host.
* Log onto your git host in Internet Explorer
* Purge your local symbol cache
Note that this approach is not guaranteed to work. Visual Studio needs to authenticate to retrieve the source files
but does not ask the user for credentials to do so. There are ways to work around this, but no mechanism is currently
provided out-of-the-box in *GitLink*.
Possible workarounds
* Include a mechanism in the pdb to retrieve credentials (using PowerShell and Windows credentials store) (see [#37](https://github.com/GitTools/GitLink/issues/37))
* Use a proxy service that does not require authentication (see [#66](https://github.com/GitTools/GitLink/issues/66) and [Source server with Git repository](https://shonnlyga.wordpress.com/2016/05/28/source-server-with-git-repository))
# Supported git providers
GitLink supports the following providers out of the box (will auto-detect based on the url):
* BitBucket
* GitHub
* Visual Studio Team Services
* Custom Provider (custom urls)
Providers that could be supported with the help of the community:
* Assembla
* Beanstalk
* CloudForge
* Codebase
* FogCreek
* Planio
* ProjectLocker
* RhodeCode
* Unfuddle
It is also possible to specify a custom url provider.
# Projects using GitLink
Below is a list of projects already using GitLink (alphabetically ordered).
- ASP.NET Boilerplate
- Catel
- CefSharp
- eXpand
- FakeItEasy
- Fluent.Ribbon
- GitLink
- MahApps.Metro
- NBitcoin
- NBitcoin.Indexer
- NEST and Elasticsearch.NET
- Orc.Analytics
- Orc.AutomaticSupport
- Orc.CommandLine
- Orc.Controls
- Orc.CrashReporting
- Orc.CsvHelper
- Orc.Feedback
- Orc.FileAssociation
- Orc.FilterBuilder
- Orc.LicenseManager
- Orc.Metadata
- Orc.Notifications
- Orc.NuGetExplorer
- Orc.ProjectManagement
- Orc.Search
- Orc.Sort
- Orc.Squirrel
- Orc.SupportPackage
- Orc.SystemInfo
- Orc.WorkspaceManagement
- Orc.Wizard
- Orchestra
- OxyPlot
- QBitNinja
- ReactiveUI
- Romantic Web
- Roslyn
- Serenity
- xUnit.net
- xUnit.net Visual Studio Runner
Are you using GitLink in your projects? Let us know and we will add your project to the list.
*Note that you can also create a pull request on this document and add it yourself.*
# Icon
Link by Dominic Whittle from The Noun Project
[NuGetDownload]: https://www.nuget.org/packages/gitlink