Home

Welcome to the LibGit2Sharp project wiki!

If you are interested in contributing to the development of this project we would love to have your help. Please take a moment to read through the contributing guide below.

General Support and Questions

If you've found a bug, want a new feature, or just have a question please use the issue tracker.

Contributing

1. Use autocrlf = true. You can do this by running this command in a shell: $ git config --global core.autocrlf input
2. Fork the project on github and create a topic branch that is named for the feature you are implementing or the bug you are fixing.
3. Write tests, and following the style of the existing tests.
4. Implement your feature or fix your bug. Please following existing coding styles and do not introduce new ones.
5. Make atomic, focused commits with good commit messages.
6. Send a Pull Request.

High Level Design Goals for the API

A lot of thought has gone into the current API design, please help keep things consistent. The following is a list of general guidelines for implementing new features in the API.

1. The API should be intuitive, discoverable, and consistent.
2. The Repository is intended to be the primary interface and root aggregate object for accessing all functionality. It is the only object that implements IDisposable.
3. GitObjects like Tree, Tag, Blob, Commit should not implement IDisposable. The consumer should not have to worry about disposing these objects when they are return from methods like repository.Lookup(sha).
4. If you do have to implement IDisposable, please use the SafeHandle pattern.
5. LibGit2Sharp should not be a 1:1 mapping of the libgit2 C API. This means that there maybe features in libgit2 that are not supported or are only exposed in a constrained manner.
6. Sketch out the API design before implementing! Here is a good example of the initial API sketch done in a gist:

using (var repo = new Repository("path\to\repo.git"))
{
    // Object lookup
    var obj = repo.Lookup("sha");
    var commit = repo.Lookup<Commit>("sha");
    var tree = repo.Lookup<Tree>("sha");
    var tag = repo.Lookup<Tag>("sha");

    // Rev walking
    foreach (var c in repo.Commits.Walk("sha")) { }
    var commits = repo.Commits.StartingAt("sha").Where(c => c).ToList();
    var sortedCommits = repo.Commits.StartingAt("sha").SortBy(SortMode.Topo).ToList();

    // Refs
    var reference = repo.Refs["refs/heads/master"];
    var allRefs = repo.Refs.ToList();
    foreach (var c in repo.Refs["HEAD"].Commits) { }
    foreach (var c in repo.Head.Commits) { }
    var headCommit = repo.Head.Commits.First();
    var allCommits = repo.Refs["HEAD"].Commits.ToList();
    var newRef = repo.Refs.CreateFrom(reference);
    var anotherNewRef = repo.Refs.CreateFrom("sha");

    // Branches
    // special kind of reference
    var allBranches = repo.Branches.ToList();
    var branch = repo.Branches["master"];
    var remoteBranch = repo.Branches["origin/master"];
    var localBranches = repo.Branches.Where(p => p.Type == BranchType.Local).ToList();
    var remoteBranches = repo.Branches.Where(p => p.Type == BranchType.Remote).ToList();
    var newBranch = repo.Branches.CreateFrom("sha");
    var anotherNewBranch = repo.Branches.CreateFrom(newBranch);
    repo.Branches.Delete(anotherNewBranch);

    // Tags
    // really another special kind of reference
    var aTag = repo.Tags["refs/tags/v1.0"];
    var allTags = repo.Tags.ToList();
    var newTag = repo.Tags.CreateFrom("sha");
    var newTag2 = repo.Tags.CreateFrom(commit);
    var newTag3 = repo.Tags.CreateFrom(reference);
}

In many cases, if you are implementing brand new parts of the API it is a good idea to sketch out how the API would be used by a consumer, post it somewhere like gists and ask for some feedback before diving in and implementing.

<script src="https://gist.github.com/890753.js?file=libgit2sharp.cs"></script>