general.c 18.3 KB
Newer Older
Scott Chacon committed
1 2
// [**libgit2**][lg] is a portable, pure C implementation of the Git core methods
// provided as a re-entrant linkable library with a solid API, allowing you
3 4
// to write native speed custom Git applications in any language which
// supports C bindings.
Scott Chacon committed
5
//
Scott Chacon committed
6 7 8
// This file is an example of using that API in a real, compilable C file.
// As the API is updated, this file will be updated to demonstrate the
// new functionality.
Scott Chacon committed
9 10 11 12 13 14 15 16 17 18
//
// If you're trying to write something in C using [libgit2][lg], you will also want
// to check out the generated [API documentation][ap] and the [Usage Guide][ug]. We've
// tried to link to the relevant sections of the API docs in each section in this file.
//
// **libgit2** only implements the core plumbing functions, not really the higher
// level porcelain stuff. For a primer on Git Internals that you will need to know
// to work with Git at this level, check out [Chapter 9][pg] of the Pro Git book.
//
// [lg]: http://libgit2.github.com
Scott Chacon committed
19
// [ap]: http://libgit2.github.com/libgit2
Scott Chacon committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
// [ug]: http://libgit2.github.com/api.html
// [pg]: http://progit.org/book/ch9-0.html

// ### Includes

// Including the `git2.h` header will include all the other libgit2 headers that you need.
// It should be the only thing you need to include in order to compile properly and get
// all the libgit2 API.
#include <git2.h>
#include <stdio.h>

int main (int argc, char** argv)
{
  // ### Opening the Repository

  // There are a couple of methods for opening a repository, this being the simplest.
  // There are also [methods][me] for specifying the index file and work tree locations, here
  // we are assuming they are in the normal places.
  //
Scott Chacon committed
39
  // [me]: http://libgit2.github.com/libgit2/#HEAD/group/repository
Scott Chacon committed
40
  git_repository *repo;
41
  if (argc > 1) {
42
    git_repository_open(&repo, argv[1]);
43
  } else {
44
    git_repository_open(&repo, "/opt/libgit2-test/.git");
45
  }
Scott Chacon committed
46 47 48 49 50 51 52 53 54 55

  // ### SHA-1 Value Conversions

  // For our first example, we will convert a 40 character hex value to the 20 byte raw SHA1 value.
  printf("*Hex to Raw*\n");
  char hex[] = "fd6e612585290339ea8bf39c692a7ff6a29cb7c3";

  // The `git_oid` is the structure that keeps the SHA value. We will use this throughout the example
  // for storing the value of the current SHA key we're working with.
  git_oid oid;
56
  git_oid_fromstr(&oid, hex);
Scott Chacon committed
57 58

  // Once we've converted the string into the oid value, we can get the raw value of the SHA.
59
  printf("Raw 20 bytes: [%.20s]\n", (&oid)->id);
Scott Chacon committed
60 61 62 63 64 65 66 67 68 69 70 71

  // Next we will convert the 20 byte raw SHA1 value to a human readable 40 char hex value.
  printf("\n*Raw to Hex*\n");
  char out[41];
  out[40] = '\0';

  // If you have a oid, you can easily get the hex value of the SHA as well.
  git_oid_fmt(out, &oid);
  printf("SHA hex string: %s\n", out);

  // ### Working with the Object Database
  // **libgit2** provides [direct access][odb] to the object database.
72 73
  // The object database is where the actual objects are stored in Git. For
  // working with raw objects, we'll need to get this structure from the
Scott Chacon committed
74
  // repository.
Scott Chacon committed
75
  // [odb]: http://libgit2.github.com/libgit2/#HEAD/group/odb
Scott Chacon committed
76
  git_odb *odb;
77
  odb = git_repository_database(repo);
Scott Chacon committed
78 79 80 81 82 83 84 85

  // #### Raw Object Reading

  printf("\n*Raw Object Read*\n");
  git_odb_object *obj;
  git_otype otype;
  const unsigned char *data;
  const char *str_type;
86
  int error;
Scott Chacon committed
87 88 89 90

  // We can read raw objects directly from the object database if we have the oid (SHA)
  // of the object.  This allows us to access objects without knowing thier type and inspect
  // the raw bytes unparsed.
91
  error = git_odb_read(&obj, odb, &oid);
Scott Chacon committed
92 93 94 95 96 97 98 99 100

  // A raw object only has three properties - the type (commit, blob, tree or tag), the size
  // of the raw data and the raw, unparsed data itself.  For a commit or tag, that raw data
  // is human readable plain ASCII text. For a blob it is just file contents, so it could be
  // text or binary data. For a tree it is a special binary format, so it's unlikely to be
  // hugely helpful as a raw object.
  data = (const unsigned char *)git_odb_object_data(obj);
  otype = git_odb_object_type(obj);

101
  // We provide methods to convert from the object type which is an enum, to a string
Scott Chacon committed
102 103
  // representation of that value (and vice-versa).
  str_type = git_object_type2string(otype);
104
  printf("object length and type: %d, %s\n",
Scott Chacon committed
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
      (int)git_odb_object_size(obj),
      str_type);

  // For proper memory management, close the object when you are done with it or it will leak
  // memory.
  git_odb_object_close(obj);

  // #### Raw Object Writing

  printf("\n*Raw Object Write*\n");

  // You can also write raw object data to Git. This is pretty cool because it gives you
  // direct access to the key/value properties of Git.  Here we'll write a new blob object
  // that just contains a simple string.  Notice that we have to specify the object type as
  // the `git_otype` enum.
120
  git_odb_write(&oid, odb, "test data", sizeof("test data") - 1, GIT_OBJ_BLOB);
Scott Chacon committed
121 122 123 124 125 126 127 128 129 130 131 132

  // Now that we've written the object, we can check out what SHA1 was generated when the
  // object was written to our database.
  git_oid_fmt(out, &oid);
  printf("Written Object: %s\n", out);

  // ### Object Parsing
  // libgit2 has methods to parse every object type in Git so you don't have to work directly
  // with the raw data. This is much faster and simpler than trying to deal with the raw data
  // yourself.

  // #### Commit Parsing
133
  // [Parsing commit objects][pco] is simple and gives you access to all the data in the commit
Scott Chacon committed
134
  // - the // author (name, email, datetime), committer (same), tree, message, encoding and parent(s).
Scott Chacon committed
135
  // [pco]: http://libgit2.github.com/libgit2/#HEAD/group/commit
Scott Chacon committed
136 137 138 139

  printf("\n*Commit Parsing*\n");

  git_commit *commit;
140
  git_oid_fromstr(&oid, "f0877d0b841d75172ec404fc9370173dfffc20d1");
Scott Chacon committed
141

142
  error = git_commit_lookup(&commit, repo, &oid);
Scott Chacon committed
143 144

  const git_signature *author, *cmtter;
145
  const char *message;
Scott Chacon committed
146 147 148 149
  time_t ctime;
  unsigned int parents, p;

  // Each of the properties of the commit object are accessible via methods, including commonly
150 151
  // needed variations, such as `git_commit_time` which returns the author time and `_message`
  // which gives you the commit message.
Scott Chacon committed
152 153 154 155 156 157 158 159 160 161
  message  = git_commit_message(commit);
  author   = git_commit_author(commit);
  cmtter   = git_commit_committer(commit);
  ctime    = git_commit_time(commit);

  // The author and committer methods return [git_signature] structures, which give you name, email
  // and `when`, which is a `git_time` structure, giving you a timestamp and timezone offset.
  printf("Author: %s (%s)\n", author->name, author->email);

  // Commits can have zero or more parents. The first (root) commit will have no parents, most commits
162
  // will have one, which is the commit it was based on, and merge commits will have two or more.
Scott Chacon committed
163 164 165 166
  // Commits can technically have any number, though it's pretty rare to have more than two.
  parents  = git_commit_parentcount(commit);
  for (p = 0;p < parents;p++) {
    git_commit *parent;
167
    git_commit_parent(&parent, commit, p);
Scott Chacon committed
168 169 170 171 172 173 174 175 176 177 178 179 180 181
    git_oid_fmt(out, git_commit_id(parent));
    printf("Parent: %s\n", out);
    git_commit_close(parent);
  }

  // Don't forget to close the object to prevent memory leaks. You will have to do this for
  // all the objects you open and parse.
  git_commit_close(commit);

  // #### Writing Commits
  //
  // libgit2 provides a couple of methods to create commit objects easily as well. There are four
  // different create signatures, we'll just show one of them here.  You can read about the other
  // ones in the [commit API docs][cd].
Scott Chacon committed
182
  // [cd]: http://libgit2.github.com/libgit2/#HEAD/group/commit
Scott Chacon committed
183 184 185

  printf("\n*Commit Writing*\n");
  git_oid tree_id, parent_id, commit_id;
186 187
  git_tree *tree;
  git_commit *parent;
Scott Chacon committed
188 189 190 191 192

  // Creating signatures for an authoring identity and time is pretty simple - you will need to have
  // this to create a commit in order to specify who created it and when.  Default values for the name
  // and email should be found in the `user.name` and `user.email` configuration options.  See the `config`
  // section of this example file to see how to access config values.
193 194 195 196
  git_signature_new((git_signature **)&author, "Scott Chacon", "schacon@gmail.com",
      123456789, 60);
  git_signature_new((git_signature **)&cmtter, "Scott A Chacon", "scott@github.com",
      987654321, 90);
Scott Chacon committed
197 198

  // Commit objects need a tree to point to and optionally one or more parents.  Here we're creating oid
199
  // objects to create the commit with, but you can also use
200 201 202 203
  git_oid_fromstr(&tree_id, "28873d96b4e8f4e33ea30f4c682fd325f7ba56ac");
  git_tree_lookup(&tree, repo, &tree_id);
  git_oid_fromstr(&parent_id, "f0877d0b841d75172ec404fc9370173dfffc20d1");
  git_commit_lookup(&parent, repo, &parent_id);
Scott Chacon committed
204 205 206 207 208 209 210 211 212

  // Here we actually create the commit object with a single call with all the values we need to create
  // the commit.  The SHA key is written to the `commit_id` variable here.
  git_commit_create_v(
    &commit_id, /* out id */
    repo,
    NULL, /* do not update the HEAD */
    author,
    cmtter,
213
    NULL, /* use default message encoding */
Scott Chacon committed
214
    "example commit",
215 216
    tree,
    1, parent);
Scott Chacon committed
217 218 219 220 221 222 223 224

  // Now we can take a look at the commit SHA we've generated.
  git_oid_fmt(out, &commit_id);
  printf("New Commit: %s\n", out);

  // #### Tag Parsing
  // You can parse and create tags with the [tag management API][tm], which functions very similarly
  // to the commit lookup, parsing and creation methods, since the objects themselves are very similar.
Scott Chacon committed
225
  // [tm]: http://libgit2.github.com/libgit2/#HEAD/group/tag
Scott Chacon committed
226 227 228 229 230 231 232
  printf("\n*Tag Parsing*\n");
  git_tag *tag;
  const char *tmessage, *tname;
  git_otype ttype;

  // We create an oid for the tag object if we know the SHA and look it up in the repository the same
  // way that we would a commit (or any other) object.
233
  git_oid_fromstr(&oid, "bc422d45275aca289c51d79830b45cecebff7c3a");
Scott Chacon committed
234

235
  error = git_tag_lookup(&tag, repo, &oid);
Scott Chacon committed
236 237

  // Now that we have the tag object, we can extract the information it generally contains: the target
238
  // (usually a commit object), the type of the target object (usually 'commit'), the name ('v1.0'),
Scott Chacon committed
239
  // the tagger (a git_signature - name, email, timestamp), and the tag message.
240
  git_tag_target((git_object **)&commit, tag);
Scott Chacon committed
241 242 243 244 245 246 247 248 249 250 251 252
  tname = git_tag_name(tag);    // "test"
  ttype = git_tag_type(tag);    // GIT_OBJ_COMMIT (otype enum)
  tmessage = git_tag_message(tag); // "tag message\n"
  printf("Tag Message: %s\n", tmessage);

  git_commit_close(commit);

  // #### Tree Parsing
  // [Tree parsing][tp] is a bit different than the other objects, in that we have a subtype which is the
  // tree entry.  This is not an actual object type in Git, but a useful structure for parsing and
  // traversing tree entries.
  //
Scott Chacon committed
253
  // [tp]: http://libgit2.github.com/libgit2/#HEAD/group/tree
Scott Chacon committed
254 255
  printf("\n*Tree Parsing*\n");

256
  const git_tree_entry *entry;
Scott Chacon committed
257 258 259
  git_object *objt;

  // Create the oid and lookup the tree object just like the other objects.
260 261
  git_oid_fromstr(&oid, "2a741c18ac5ff082a7caaec6e74db3075a1906b5");
  git_tree_lookup(&tree, repo, &oid);
Scott Chacon committed
262 263 264 265 266

  // Getting the count of entries in the tree so you can iterate over them if you want to.
  int cnt = git_tree_entrycount(tree); // 3
  printf("tree entries: %d\n", cnt);

267
  entry = git_tree_entry_byindex(tree, 0);
Scott Chacon committed
268 269 270
  printf("Entry name: %s\n", git_tree_entry_name(entry)); // "hello.c"

  // You can also access tree entries by name if you know the name of the entry you're looking for.
271
  entry = git_tree_entry_byname(tree, "hello.c");
Scott Chacon committed
272 273 274 275 276 277 278 279 280 281 282 283 284
  git_tree_entry_name(entry); // "hello.c"

  // Once you have the entry object, you can access the content or subtree (or commit, in the case
  // of submodules) that it points to.  You can also get the mode if you want.
  git_tree_entry_2object(&objt, repo, entry); // blob

  // Remember to close the looked-up object once you are done using it
  git_object_close(objt);

  // #### Blob Parsing
  //
  // The last object type is the simplest and requires the least parsing help. Blobs are just file
  // contents and can contain anything, there is no structure to it. The main advantage to using the
285
  // [simple blob api][ba] is that when you're creating blobs you don't have to calculate the size
Scott Chacon committed
286 287 288
  // of the content.  There is also a helper for reading a file from disk and writing it to the db and
  // getting the oid back so you don't have to do all those steps yourself.
  //
Scott Chacon committed
289
  // [ba]: http://libgit2.github.com/libgit2/#HEAD/group/blob
Scott Chacon committed
290 291 292 293

  printf("\n*Blob Parsing*\n");
  git_blob *blob;

294 295
  git_oid_fromstr(&oid, "af7574ea73f7b166f869ef1a39be126d9a186ae0");
  git_blob_lookup(&blob, repo, &oid);
Scott Chacon committed
296 297 298 299 300

  // You can access a buffer with the raw contents of the blob directly.
  // Note that this buffer may not be contain ASCII data for certain blobs (e.g. binary files):
  // do not consider the buffer a NULL-terminated string, and use the `git_blob_rawsize` attribute to
  // find out its exact size in bytes
301 302
  printf("Blob Size: %ld\n", git_blob_rawsize(blob)); // 8
  git_blob_rawcontent(blob); // "content"
Scott Chacon committed
303 304 305 306 307 308 309 310 311

  // ### Revwalking
  //
  // The libgit2 [revision walking api][rw] provides methods to traverse the directed graph created
  // by the parent pointers of the commit objects.  Since all commits point back to the commit that
  // came directly before them, you can walk this parentage as a graph and find all the commits that
  // were ancestors of (reachable from) a given starting point.  This can allow you to create `git log`
  // type functionality.
  //
Scott Chacon committed
312
  // [rw]: http://libgit2.github.com/libgit2/#HEAD/group/revwalk
Scott Chacon committed
313 314 315 316 317

  printf("\n*Revwalking*\n");
  git_revwalk *walk;
  git_commit *wcommit;

318
  git_oid_fromstr(&oid, "f0877d0b841d75172ec404fc9370173dfffc20d1");
Scott Chacon committed
319 320 321 322 323 324 325

  // To use the revwalker, create a new walker, tell it how you want to sort the output and then push
  // one or more starting points onto the walker.  If you want to emulate the output of `git log` you
  // would push the SHA of the commit that HEAD points to into the walker and then start traversing them.
  // You can also 'hide' commits that you want to stop at or not see any of their ancestors.  So if you
  // want to emulate `git log branch1..branch2`, you would push the oid of `branch2` and hide the oid
  // of `branch1`.
326
  git_revwalk_new(&walk, repo);
Scott Chacon committed
327
  git_revwalk_sorting(walk, GIT_SORT_TOPOLOGICAL | GIT_SORT_REVERSE);
328
  git_revwalk_push(walk, &oid);
Scott Chacon committed
329 330 331 332 333 334 335 336 337 338

  const git_signature *cauth;
  const char *cmsg;

  // Now that we have the starting point pushed onto the walker, we can start asking for ancestors. It
  // will return them in the sorting order we asked for as commit oids.
  // We can then lookup and parse the commited pointed at by the returned OID;
  // note that this operation is specially fast since the raw contents of the commit object will
  // be cached in memory
  while ((git_revwalk_next(&oid, walk)) == GIT_SUCCESS) {
339
    error = git_commit_lookup(&wcommit, repo, &oid);
340
    cmsg  = git_commit_message(wcommit);
Scott Chacon committed
341 342 343 344 345 346 347 348 349 350 351 352
    cauth = git_commit_author(wcommit);
    printf("%s (%s)\n", cmsg, cauth->email);
    git_commit_close(wcommit);
  }

  // Like the other objects, be sure to free the revwalker when you're done to prevent memory leaks.
  // Also, make sure that the repository being walked it not deallocated while the walk is in
  // progress, or it will result in undefined behavior
  git_revwalk_free(walk);

  // ### Index File Manipulation
  //
353
  // The [index file API][gi] allows you to read, traverse, update and write the Git index file
Scott Chacon committed
354 355
  // (sometimes thought of as the staging area).
  //
Scott Chacon committed
356
  // [gi]: http://libgit2.github.com/libgit2/#HEAD/group/index
Scott Chacon committed
357 358 359 360

  printf("\n*Index Walking*\n");

  git_index *index;
361
  unsigned int i, ecount;
Scott Chacon committed
362 363 364 365

  // You can either open the index from the standard location in an open repository, as we're doing
  // here, or you can open and manipulate any index file with `git_index_open_bare()`. The index
  // for the repository will be located and loaded from disk.
366
  git_repository_index(&index, repo);
Scott Chacon committed
367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387

  // For each entry in the index, you can get a bunch of information including the SHA (oid), path
  // and mode which map to the tree objects that are written out.  It also has filesystem properties
  // to help determine what to inspect for changes (ctime, mtime, dev, ino, uid, gid, file_size and flags)
  // All these properties are exported publicly in the `git_index_entry` struct
  ecount = git_index_entrycount(index);
  for (i = 0; i < ecount; ++i) {
    git_index_entry *e = git_index_get(index, i);

    printf("path: %s\n", e->path);
    printf("mtime: %d\n", (int)e->mtime.seconds);
    printf("fs: %d\n", (int)e->file_size);
  }

  git_index_free(index);

  // ### References
  //
  // The [reference API][ref] allows you to list, resolve, create and update references such as
  // branches, tags and remote references (everything in the .git/refs directory).
  //
Scott Chacon committed
388
  // [ref]: http://libgit2.github.com/libgit2/#HEAD/group/reference
Scott Chacon committed
389 390 391 392 393 394

  printf("\n*Reference Listing*\n");

  // Here we will implement something like `git for-each-ref` simply listing out all available
  // references and the object SHA they resolve to.
  git_strarray ref_list;
395
  git_reference_listall(&ref_list, repo, GIT_REF_LISTALL);
Scott Chacon committed
396

397
  const char *refname;
Scott Chacon committed
398 399 400 401 402 403
  git_reference *ref;

  // Now that we have the list of reference names, we can lookup each ref one at a time and
  // resolve them to the SHA, then print both values out.
  for (i = 0; i < ref_list.count; ++i) {
    refname = ref_list.strings[i];
404
    git_reference_lookup(&ref, repo, refname);
Scott Chacon committed
405 406 407 408 409 410 411 412 413 414

    switch (git_reference_type(ref)) {
    case GIT_REF_OID:
      git_oid_fmt(out, git_reference_oid(ref));
      printf("%s [%s]\n", refname, out);
      break;

    case GIT_REF_SYMBOLIC:
      printf("%s => %s\n", refname, git_reference_target(ref));
      break;
415 416 417
    default:
      fprintf(stderr, "Unexpected reference type\n");
      exit(1);
Scott Chacon committed
418 419 420 421 422
    }
  }

  git_strarray_free(&ref_list);

423 424 425 426 427 428 429 430 431 432 433 434 435 436 437
  // ### Config Files
  //
  // The [config API][config] allows you to list and updatee config values in
  // any of the accessible config file locations (system, global, local).
  //
  // [config]: http://libgit2.github.com/libgit2/#HEAD/group/config

  printf("\n*Config Listing*\n");

  const char *email;
  int j;

  git_config *cfg;

  // Open a config object so we can read global values from it.
438
  git_config_open_ondisk(&cfg, "~/.gitconfig");
439 440 441 442 443 444 445

  git_config_get_int(cfg, "help.autocorrect", &j);
  printf("Autocorrect: %d\n", j);

  git_config_get_string(cfg, "user.email", &email);
  printf("Email: %s\n", email);

Scott Chacon committed
446 447
  // Finally, when you're done with the repository, you can free it as well.
  git_repository_free(repo);
448 449

  return 0;
Scott Chacon committed
450 451
}