general.c 19.8 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
/*
 * libgit2 "general" example - shows basic libgit2 concepts
 *
 * Written by the libgit2 contributors
 *
 * To the extent possible under law, the author(s) have dedicated all copyright
 * and related and neighboring rights to this software to the public domain
 * worldwide. This software is distributed without any warranty.
 *
 * You should have received a copy of the CC0 Public Domain Dedication along
 * with this software. If not, see
 * <http://creativecommons.org/publicdomain/zero/1.0/>.
 */

15 16 17 18
// [**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 to write native speed custom Git applications in any
// language which supports C bindings.
Scott Chacon committed
19
//
Scott Chacon committed
20
// This file is an example of using that API in a real, compilable C file.
21 22
// As the API is updated, this file will be updated to demonstrate the new
// functionality.
Scott Chacon committed
23
//
24 25 26
// If you're trying to write something in C using [libgit2][lg], you should
// also check out the generated [API documentation][ap]. We try to link to
// the relevant sections of the API docs in each section in this file.
Scott Chacon committed
27
//
28 29 30 31
// **libgit2** (for the most part) 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.
Scott Chacon committed
32 33
//
// [lg]: http://libgit2.github.com
Scott Chacon committed
34
// [ap]: http://libgit2.github.com/libgit2
Scott Chacon committed
35 36 37 38
// [pg]: http://progit.org/book/ch9-0.html

// ### Includes

39 40 41
// 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.
Scott Chacon committed
42 43 44
#include <git2.h>
#include <stdio.h>

45 46 47 48 49
// Almost all libgit2 functions return 0 on success or negative on error.
// This is not production quality error checking, but should be sufficient
// as an example.
static void check_error(int error_code, const char *action)
{
50
	const git_error *error = giterr_last();
51 52 53 54 55 56 57 58 59
	if (!error_code)
		return;

	printf("Error %d %s - %s\n", error_code, action,
		   (error && error->message) ? error->message : "???");

	exit(1);
}

Scott Chacon committed
60 61
int main (int argc, char** argv)
{
62 63 64 65
  // Initialize the library, this will set up any global state which libgit2 needs
  // including threading and crypto
  git_libgit2_init();

Scott Chacon committed
66 67
  // ### Opening the Repository

68 69 70
  // 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 assume they are in the normal places.
71
	//
72
	// (Try running this program against tests/resources/testrepo.git.)
Scott Chacon committed
73
  //
Scott Chacon committed
74
  // [me]: http://libgit2.github.com/libgit2/#HEAD/group/repository
75 76
  int error;
  const char *repo_path = (argc > 1) ? argv[1] : "/opt/libgit2-test/.git";
Scott Chacon committed
77
  git_repository *repo;
78 79 80

  error = git_repository_open(&repo, repo_path);
  check_error(error, "opening repository");
Scott Chacon committed
81 82 83

  // ### SHA-1 Value Conversions

84 85
  // For our first example, we will convert a 40 character hex value to the
  // 20 byte raw SHA1 value.
Scott Chacon committed
86
  printf("*Hex to Raw*\n");
87
  char hex[] = "4a202b346bb0fb0db7eff3cffeb3c70babbd2045";
Scott Chacon committed
88

89 90 91
  // 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.
Scott Chacon committed
92
  git_oid oid;
93
  git_oid_fromstr(&oid, hex);
Scott Chacon committed
94

95
  // Once we've converted the string into the oid value, we can get the raw
96
  // value of the SHA by accessing `oid.id`
Scott Chacon committed
97

98 99
  // Next we will convert the 20 byte raw SHA1 value to a human readable 40
  // char hex value.
Scott Chacon committed
100
  printf("\n*Raw to Hex*\n");
101 102
  char out[GIT_OID_HEXSZ+1];
  out[GIT_OID_HEXSZ] = '\0';
Scott Chacon committed
103 104 105 106 107 108

  // 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
109 110 111

  // **libgit2** provides [direct access][odb] to the object database.  The
  // object database is where the actual objects are stored in Git. For
112
  // working with raw objects, we'll need to get this structure from the
Scott Chacon committed
113
  // repository.
114
  //
Scott Chacon committed
115
  // [odb]: http://libgit2.github.com/libgit2/#HEAD/group/odb
Scott Chacon committed
116
  git_odb *odb;
117
  git_repository_odb(&odb, repo);
Scott Chacon committed
118 119 120 121 122 123 124 125 126

  // #### Raw Object Reading

  printf("\n*Raw Object Read*\n");
  git_odb_object *obj;
  git_otype otype;
  const unsigned char *data;
  const char *str_type;

127 128
  // 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
Will Stamper committed
129
  // knowing their type and inspect the raw bytes unparsed.
130
  error = git_odb_read(&obj, odb, &oid);
131 132 133 134 135 136 137 138
  check_error(error, "finding object in repository");

  // 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.
Scott Chacon committed
139 140 141
  data = (const unsigned char *)git_odb_object_data(obj);
  otype = git_odb_object_type(obj);

142 143
  // We provide methods to convert from the object type which is an enum, to
  // a string representation of that value (and vice-versa).
Scott Chacon committed
144
  str_type = git_object_type2string(otype);
145
  printf("object length and type: %d, %s\n",
Scott Chacon committed
146 147 148
      (int)git_odb_object_size(obj),
      str_type);

149 150
  // For proper memory management, close the object when you are done with
  // it or it will leak memory.
151
  git_odb_object_free(obj);
Scott Chacon committed
152 153 154 155 156

  // #### Raw Object Writing

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

157 158 159 160
  // 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.
161
  git_odb_write(&oid, odb, "test data", sizeof("test data") - 1, GIT_OBJ_BLOB);
Scott Chacon committed
162

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

  // ### Object Parsing
169 170 171 172

  // 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.
Scott Chacon committed
173 174

  // #### Commit Parsing
175 176 177 178 179

  // [Parsing commit objects][pco] is simple and gives you access to all the
  // data in the commit - the author (name, email, datetime), committer
  // (same), tree, message, encoding and parent(s).
  //
Scott Chacon committed
180
  // [pco]: http://libgit2.github.com/libgit2/#HEAD/group/commit
Scott Chacon committed
181 182 183 184

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

  git_commit *commit;
185
  git_oid_fromstr(&oid, "8496071c1b46c854b31185ea97743be6a8774479");
Scott Chacon committed
186

187
  error = git_commit_lookup(&commit, repo, &oid);
188
  check_error(error, "looking up commit");
Scott Chacon committed
189 190

  const git_signature *author, *cmtter;
191
  const char *message;
Scott Chacon committed
192 193 194
  time_t ctime;
  unsigned int parents, p;

195 196 197 198
  // Each of the properties of the commit object are accessible via methods,
  // including commonly needed variations, such as `git_commit_time` which
  // returns the author time and `git_commit_message` which gives you the
  // commit message (as a NUL-terminated string).
Scott Chacon committed
199 200 201 202 203
  message  = git_commit_message(commit);
  author   = git_commit_author(commit);
  cmtter   = git_commit_committer(commit);
  ctime    = git_commit_time(commit);

204 205 206
  // 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.
Scott Chacon committed
207 208
  printf("Author: %s (%s)\n", author->name, author->email);

209 210 211 212
  // Commits can have zero or more parents. The first (root) commit will
  // have no parents, most commits will have one (i.e. the commit it was
  // based on) and merge commits will have two or more.  Commits can
  // technically have any number, though it's rare to have more than two.
Scott Chacon committed
213 214 215
  parents  = git_commit_parentcount(commit);
  for (p = 0;p < parents;p++) {
    git_commit *parent;
216
    git_commit_parent(&parent, commit, p);
Scott Chacon committed
217 218
    git_oid_fmt(out, git_commit_id(parent));
    printf("Parent: %s\n", out);
219
    git_commit_free(parent);
Scott Chacon committed
220 221
  }

222 223
  // 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.
224
  git_commit_free(commit);
Scott Chacon committed
225 226

  // #### Writing Commits
227 228 229 230 231

  // 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
232
  //
Scott Chacon committed
233
  // [cd]: http://libgit2.github.com/libgit2/#HEAD/group/commit
Scott Chacon committed
234 235 236

  printf("\n*Commit Writing*\n");
  git_oid tree_id, parent_id, commit_id;
237 238
  git_tree *tree;
  git_commit *parent;
Scott Chacon committed
239

240 241 242 243 244 245 246 247 248 249 250 251 252
  // Creating signatures for an authoring identity and time is simple.  You
  // will need to do this to specify who created a commit 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.
  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);

  // Commit objects need a tree to point to and optionally one or more
  // parents.  Here we're creating oid objects to create the commit with,
  // but you can also use
253
  git_oid_fromstr(&tree_id, "f60079018b664e4e79329a7ef9559c8d9e0378d1");
254
  git_tree_lookup(&tree, repo, &tree_id);
255
  git_oid_fromstr(&parent_id, "5b5b025afb0b4c913b4c338a42934a3863bf3644");
256
  git_commit_lookup(&parent, repo, &parent_id);
Scott Chacon committed
257

258 259 260
  // 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.
Scott Chacon committed
261 262 263 264 265 266
  git_commit_create_v(
    &commit_id, /* out id */
    repo,
    NULL, /* do not update the HEAD */
    author,
    cmtter,
267
    NULL, /* use default message encoding */
Scott Chacon committed
268
    "example commit",
269 270
    tree,
    1, parent);
Scott Chacon committed
271 272 273 274 275 276

  // 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
277 278 279 280 281

  // 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
282
  // [tm]: http://libgit2.github.com/libgit2/#HEAD/group/tag
Scott Chacon committed
283 284 285 286 287
  printf("\n*Tag Parsing*\n");
  git_tag *tag;
  const char *tmessage, *tname;
  git_otype ttype;

288 289
  // We create an oid for the tag object if we know the SHA and look it up
  // the same way that we would a commit (or any other object).
290
  git_oid_fromstr(&oid, "b25fa35b38051e4ae45d4222e795f9df2e43f1d1");
Scott Chacon committed
291

292
  error = git_tag_lookup(&tag, repo, &oid);
293
  check_error(error, "looking up tag");
Scott Chacon committed
294

295 296 297 298
  // Now that we have the tag object, we can extract the information it
  // generally contains: the target (usually a commit object), the type of
  // the target object (usually 'commit'), the name ('v1.0'), the tagger (a
  // git_signature - name, email, timestamp), and the tag message.
299
  git_tag_target((git_object **)&commit, tag);
300 301 302
  tname = git_tag_name(tag);		// "test"
  ttype = git_tag_target_type(tag);	// GIT_OBJ_COMMIT (otype enum)
  tmessage = git_tag_message(tag);	// "tag message\n"
Scott Chacon committed
303 304
  printf("Tag Message: %s\n", tmessage);

305
  git_commit_free(commit);
Scott Chacon committed
306 307

  // #### Tree Parsing
308 309 310 311 312

  // [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
313
  //
Scott Chacon committed
314
  // [tp]: http://libgit2.github.com/libgit2/#HEAD/group/tree
Scott Chacon committed
315 316
  printf("\n*Tree Parsing*\n");

317
  const git_tree_entry *entry;
Scott Chacon committed
318 319 320
  git_object *objt;

  // Create the oid and lookup the tree object just like the other objects.
321 322
  git_oid_fromstr(&oid, "2a741c18ac5ff082a7caaec6e74db3075a1906b5");
  git_tree_lookup(&tree, repo, &oid);
Scott Chacon committed
323

324 325
  // Getting the count of entries in the tree so you can iterate over them
  // if you want to.
326 327
  size_t cnt = git_tree_entrycount(tree); // 3
  printf("tree entries: %d\n", (int)cnt);
Scott Chacon committed
328

329
  entry = git_tree_entry_byindex(tree, 0);
Scott Chacon committed
330 331
  printf("Entry name: %s\n", git_tree_entry_name(entry)); // "hello.c"

332 333
  // You can also access tree entries by name if you know the name of the
  // entry you're looking for.
334
  entry = git_tree_entry_byname(tree, "README");
Scott Chacon committed
335 336
  git_tree_entry_name(entry); // "hello.c"

337 338 339
  // 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.
340
  git_tree_entry_to_object(&objt, repo, entry); // blob
Scott Chacon committed
341 342

  // Remember to close the looked-up object once you are done using it
343
  git_object_free(objt);
Scott Chacon committed
344 345

  // #### Blob Parsing
346 347 348 349 350 351 352 353

  // 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 [simple blob
  // api][ba] is that when you're creating blobs you don't have to calculate
  // the size 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
354
  //
Scott Chacon committed
355
  // [ba]: http://libgit2.github.com/libgit2/#HEAD/group/blob
Scott Chacon committed
356 357 358 359

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

360
  git_oid_fromstr(&oid, "1385f264afb75a56a5bec74243be9b367ba4ca08");
361
  git_blob_lookup(&blob, repo, &oid);
Scott Chacon committed
362 363

  // You can access a buffer with the raw contents of the blob directly.
364 365 366 367
  // 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
368
  printf("Blob Size: %ld\n", (long)git_blob_rawsize(blob)); // 8
369
  git_blob_rawcontent(blob); // "content"
Scott Chacon committed
370 371

  // ### Revwalking
372 373 374 375 376 377 378

  // 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
379
  //
Scott Chacon committed
380
  // [rw]: http://libgit2.github.com/libgit2/#HEAD/group/revwalk
Scott Chacon committed
381 382 383 384 385

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

386
  git_oid_fromstr(&oid, "5b5b025afb0b4c913b4c338a42934a3863bf3644");
Scott Chacon committed
387

388 389 390 391 392 393 394
  // 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
Scott Chacon committed
395
  // of `branch1`.
396
  git_revwalk_new(&walk, repo);
Scott Chacon committed
397
  git_revwalk_sorting(walk, GIT_SORT_TOPOLOGICAL | GIT_SORT_REVERSE);
398
  git_revwalk_push(walk, &oid);
Scott Chacon committed
399 400 401 402

  const git_signature *cauth;
  const char *cmsg;

403 404
  // Now that we have the starting point pushed onto the walker, we start
  // asking for ancestors. It will return them in the sorting order we asked
Will Stamper committed
405
  // for as commit oids.  We can then lookup and parse the committed pointed
406 407
  // 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
408
  while ((git_revwalk_next(&oid, walk)) == 0) {
409
    error = git_commit_lookup(&wcommit, repo, &oid);
410 411
	check_error(error, "looking up commit during revwalk");

412
    cmsg  = git_commit_message(wcommit);
Scott Chacon committed
413 414
    cauth = git_commit_author(wcommit);
    printf("%s (%s)\n", cmsg, cauth->email);
415

416
    git_commit_free(wcommit);
Scott Chacon committed
417 418
  }

419 420 421 422
  // 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
Scott Chacon committed
423 424 425
  git_revwalk_free(walk);

  // ### Index File Manipulation
426 427 428

  // The [index file API][gi] allows you to read, traverse, update and write
  // the Git index file (sometimes thought of as the staging area).
Scott Chacon committed
429
  //
Scott Chacon committed
430
  // [gi]: http://libgit2.github.com/libgit2/#HEAD/group/index
Scott Chacon committed
431 432 433 434

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

  git_index *index;
435
  unsigned int i, ecount;
Scott Chacon committed
436

437 438 439 440
  // 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.
441
  git_repository_index(&index, repo);
Scott Chacon committed
442

443 444 445 446 447 448
  // 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
Scott Chacon committed
449 450
  ecount = git_index_entrycount(index);
  for (i = 0; i < ecount; ++i) {
Ben Straub committed
451
    const git_index_entry *e = git_index_get_byindex(index, i);
Scott Chacon committed
452 453 454 455 456 457 458 459 460

    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
461 462 463 464

  // 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
465
  //
Scott Chacon committed
466
  // [ref]: http://libgit2.github.com/libgit2/#HEAD/group/reference
Scott Chacon committed
467 468 469

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

470 471
  // Here we will implement something like `git for-each-ref` simply listing
  // out all available references and the object SHA they resolve to.
Scott Chacon committed
472
  git_strarray ref_list;
473
  git_reference_list(&ref_list, repo);
Scott Chacon committed
474

475
  const char *refname;
Scott Chacon committed
476 477
  git_reference *ref;

478 479
  // 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.
Scott Chacon committed
480 481
  for (i = 0; i < ref_list.count; ++i) {
    refname = ref_list.strings[i];
482
    git_reference_lookup(&ref, repo, refname);
Scott Chacon committed
483 484 485

    switch (git_reference_type(ref)) {
    case GIT_REF_OID:
486
      git_oid_fmt(out, git_reference_target(ref));
Scott Chacon committed
487 488 489 490
      printf("%s [%s]\n", refname, out);
      break;

    case GIT_REF_SYMBOLIC:
491
      printf("%s => %s\n", refname, git_reference_symbolic_target(ref));
Scott Chacon committed
492
      break;
493 494 495
    default:
      fprintf(stderr, "Unexpected reference type\n");
      exit(1);
Scott Chacon committed
496 497 498 499 500
    }
  }

  git_strarray_free(&ref_list);

501
  // ### Config Files
502 503 504

  // The [config API][config] allows you to list and updatee config values
  // in any of the accessible config file locations (system, global, local).
505 506 507 508 509 510
  //
  // [config]: http://libgit2.github.com/libgit2/#HEAD/group/config

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

  const char *email;
511
  int32_t j;
512 513 514 515

  git_config *cfg;

  // Open a config object so we can read global values from it.
516 517 518
  char config_path[256];
  sprintf(config_path, "%s/config", repo_path);
  check_error(git_config_open_ondisk(&cfg, config_path), "opening config");
519

520
  git_config_get_int32(&j, cfg, "help.autocorrect");
521 522
  printf("Autocorrect: %d\n", j);

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

Scott Chacon committed
526 527
  // Finally, when you're done with the repository, you can free it as well.
  git_repository_free(repo);
528 529

  return 0;
Scott Chacon committed
530 531
}