Skip to content

G
git2
Commit 85c6730c by Ben Straub
Options

Format comments for use with docco

parent dbdb22b3
Showing with 86 additions and 72 deletions
examples/diff.c
......@@ -7,7 +7,7 @@
#include "common.h"
/*
/**
* This example demonstrates the use of the libgit2 diff APIs to
* create `git_diff` objects and display them, emulating a number of
* core Git `diff` command line options.
......@@ -26,11 +26,7 @@ static const char *colors[] = {
"\033[36m" /* cyan */
};
/* this implements very rudimentary colorized output */
static int color_printer(
const git_diff_delta*, const git_diff_hunk*, const git_diff_line*, void*);
/* the 'opts' struct captures all the various parsed command line options */
/** The 'opts' struct captures all the various parsed command line options. */
struct opts {
git_diff_options diffopts;
git_diff_find_options findopts;
......@@ -43,6 +39,8 @@ struct opts {
};
static void parse_opts(struct opts *o, int argc, char *argv[]);
static int color_printer(
const git_diff_delta*, const git_diff_hunk*, const git_diff_line*, void*);
int main(int argc, char *argv[])
{
......@@ -61,12 +59,14 @@ int main(int argc, char *argv[])
check_lg2(git_repository_open_ext(&repo, o.dir, 0, NULL),
"Could not open repository", o.dir);
/* Possible argument patterns:
* <sha1> <sha2>
* <sha1> --cached
* <sha1>
* --cached
* nothing
/**
* Possible argument patterns:
*
* * <sha1> <sha2>
* * <sha1> --cached
* * <sha1>
* * --cached
* * nothing
*
* Currently ranged arguments like <sha1>..<sha2> and <sha1>...<sha2>
* are not supported in this example
......@@ -100,14 +100,14 @@ int main(int argc, char *argv[])
git_diff_index_to_workdir(&diff, repo, NULL, &o.diffopts),
"diff index to working directory", NULL);
/* apply rename and copy detection if requested */
/** Apply rename and copy detection if requested. */
if ((o.findopts.flags & GIT_DIFF_FIND_ALL) != 0)
check_lg2(
git_diff_find_similar(diff, &o.findopts),
"finding renames and copies", NULL);
/* generate simple output using libgit2 display helper */
/** Generate simple output using libgit2 display helper. */
if (o.color >= 0)
fputs(colors[0], stdout);
......@@ -119,7 +119,7 @@ int main(int argc, char *argv[])
if (o.color >= 0)
fputs(colors[0], stdout);
/* cleanup before exiting */
/** Cleanup before exiting. */
git_diff_free(diff);
git_tree_free(t1);
......@@ -141,6 +141,7 @@ static void usage(const char *message, const char *arg)
exit(1);
}
/** This implements very rudimentary colorized output. */
static int color_printer(
const git_diff_delta *delta,
const git_diff_hunk *hunk,
......@@ -177,7 +178,7 @@ static void parse_opts(struct opts *o, int argc, char *argv[])
{
struct args_info args = ARGS_INFO_INIT;
/* parse arguments as copied from git-diff */
/* Parse arguments as copied from git-diff. */
for (args.pos = 1; args.pos < argc; ++args.pos) {
const char *a = argv[args.pos];
......
examples/init.c
/*
* Copyright (C) the libgit2 contributors. All rights reserved.
*
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
*/
#include "common.h"
/**
* This is a sample program that is similar to "git init". See the
* documentation for that (try "git help init") to understand what this
* program is emulating.
......@@ -8,16 +17,9 @@
* This also contains a special additional option that regular "git init"
* does not support which is "--initial-commit" to make a first empty commit.
* That is demonstrated in the "create_initial_commit" helper function.
*
* Copyright (C) the libgit2 contributors. All rights reserved.
*
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
*/
#include "common.h"
/* forward declarations of helpers */
/** Forward declarations of helpers */
struct opts {
int no_options;
int quiet;
......@@ -41,17 +43,19 @@ int main(int argc, char *argv[])
parse_opts(&o, argc, argv);
/* Initialize repository */
/* Initialize repository. */
if (o.no_options) {
/* No options were specified, so let's demonstrate the default
/**
* No options were specified, so let's demonstrate the default
* simple case of git_repository_init() API usage...
*/
check_lg2(git_repository_init(&repo, o.dir, 0),
"Could not initialize repository", NULL);
}
else {
/* Some command line options were specified, so we'll use the
/**
* Some command line options were specified, so we'll use the
* extended init API to handle them
*/
git_repository_init_options initopts = GIT_REPOSITORY_INIT_OPTIONS_INIT;
......@@ -66,7 +70,8 @@ int main(int argc, char *argv[])
}
if (o.gitdir) {
/* if you specified a separate git directory, then initialize
/**
* If you specified a separate git directory, then initialize
* the repository at that path and use the second path as the
* working directory of the repository (with a git-link file)
*/
......@@ -81,7 +86,7 @@ int main(int argc, char *argv[])
"Could not initialize repository", NULL);
}
/* Print a message to stdout like "git init" does */
/** Print a message to stdout like "git init" does. */
if (!o.quiet) {
if (o.bare || o.gitdir)
......@@ -92,7 +97,8 @@ int main(int argc, char *argv[])
printf("Initialized empty Git repository in %s\n", o.dir);
}
/* As an extension to the basic "git init" command, this example
/**
* As an extension to the basic "git init" command, this example
* gives the option to create an empty initial commit. This is
* mostly to demonstrate what it takes to do that, but also some
* people like to have that empty base commit in their repo.
......@@ -108,7 +114,8 @@ int main(int argc, char *argv[])
return 0;
}
/* Unlike regular "git init", this example shows how to create an initial
/**
* Unlike regular "git init", this example shows how to create an initial
* empty commit in the repository. This is the helper function that does
* that.
*/
......@@ -119,7 +126,7 @@ static void create_initial_commit(git_repository *repo)
git_oid tree_id, commit_id;
git_tree *tree;
/* First use the config to initialize a commit signature for the user */
/** First use the config to initialize a commit signature for the user. */
if (git_signature_default(&sig, repo) < 0)
fatal("Unable to create a commit signature.",
......@@ -130,7 +137,8 @@ static void create_initial_commit(git_repository *repo)
if (git_repository_index(&index, repo) < 0)
fatal("Could not open repository index", NULL);
/* Outside of this example, you could call git_index_add_bypath()
/**
* Outside of this example, you could call git_index_add_bypath()
* here to put actual files into the index. For our purposes, we'll
* leave it empty for now.
*/
......@@ -143,7 +151,8 @@ static void create_initial_commit(git_repository *repo)
if (git_tree_lookup(&tree, repo, &tree_id) < 0)
fatal("Could not look up initial tree", NULL);
/* Ready to create the initial commit
/**
* Ready to create the initial commit.
*
* Normally creating a commit would involve looking up the current
* HEAD commit and making that be the parent of the initial commit,
......@@ -155,7 +164,7 @@ static void create_initial_commit(git_repository *repo)
NULL, "Initial commit", tree, 0) < 0)
fatal("Could not create the initial commit", NULL);
/* Clean up so we don't leak memory */
/** Clean up so we don't leak memory. */
git_tree_free(tree);
git_signature_free(sig);
......@@ -171,7 +180,7 @@ static void usage(const char *error, const char *arg)
exit(1);
}
/* parse the tail of the --shared= argument */
/** Parse the tail of the --shared= argument. */
static uint32_t parse_shared(const char *shared)
{
if (!strcmp(shared, "false") || !strcmp(shared, "umask"))
......@@ -204,7 +213,7 @@ static void parse_opts(struct opts *o, int argc, char *argv[])
struct args_info args = ARGS_INFO_INIT;
const char *sharedarg;
/* Process arguments */
/** Process arguments. */
for (args.pos = 1; args.pos < argc; ++args.pos) {
char *a = argv[args.pos];
......
examples/log.c
......@@ -7,23 +7,25 @@
#include "common.h"
/*
/**
* This example demonstrates the libgit2 rev walker APIs to roughly
* simulate the output of `git log` and a few of command line arguments.
* `git log` has many many options and this only shows a few of them.
*
* This does not have:
*
* - Robust error handling
* - Colorized or paginated output formatting
* - Most of the `git log` options
*
* This does have:
*
* - Examples of translating command line arguments to equivalent libgit2
* revwalker configuration calls
* - Simplified options to apply pathspec limits and to show basic diffs
*/
/* log_state represents walker being configured while handling options */
/** log_state represents walker being configured while handling options */
struct log_state {
git_repository *repo;
const char *repodir;
......@@ -33,12 +35,12 @@ struct log_state {
int revisions;
};
/* utility functions that are called to configure the walker */
/** utility functions that are called to configure the walker */
static void set_sorting(struct log_state *s, unsigned int sort_mode);
static void push_rev(struct log_state *s, git_object *obj, int hide);
static int add_revision(struct log_state *s, const char *revstr);
/* log_options holds other command line options that affect log output */
/** log_options holds other command line options that affect log output */
struct log_options {
int show_diff;
int skip, limit;
......@@ -49,7 +51,7 @@ struct log_options {
char *committer;
};
/* utility functions that parse options and help with log output */
/** utility functions that parse options and help with log output */
static int parse_options(
struct log_state *s, struct log_options *opt, int argc, char **argv);
static void print_time(const git_time *intime, const char *prefix);
......@@ -69,7 +71,7 @@ int main(int argc, char *argv[])
git_threads_init();
/* parse arguments and set up revwalker */
/** Parse arguments and set up revwalker. */
last_arg = parse_options(&s, &opt, argc, argv);
......@@ -82,7 +84,7 @@ int main(int argc, char *argv[])
if (!s.revisions)
add_revision(&s, NULL);
/* use the revwalker to traverse the history */
/** Use the revwalker to traverse the history. */
printed = count = 0;
......@@ -163,12 +165,12 @@ int main(int argc, char *argv[])
return 0;
}
/* push object (for hide or show) onto revwalker */
/** Push object (for hide or show) onto revwalker. */
static void push_rev(struct log_state *s, git_object *obj, int hide)
{
hide = s->hide ^ hide;
/* create revwalker on demand if it doesn't already exist */
/** Create revwalker on demand if it doesn't already exist. */
if (!s->walker) {
check_lg2(git_revwalk_new(&s->walker, s->repo),
"Could not create revision walker", NULL);
......@@ -188,13 +190,13 @@ static void push_rev(struct log_state *s, git_object *obj, int hide)
git_object_free(obj);
}
/* parse revision string and add revs to walker */
/** Parse revision string and add revs to walker. */
static int add_revision(struct log_state *s, const char *revstr)
{
git_revspec revs;
int hide = 0;
/* open repo on demand if it isn't already open */
/** Open repo on demand if it isn't already open. */
if (!s->repo) {
if (!s->repodir) s->repodir = ".";
check_lg2(git_repository_open_ext(&s->repo, s->repodir, 0, NULL),
......@@ -238,17 +240,17 @@ static int add_revision(struct log_state *s, const char *revstr)
return 0;
}
/* update revwalker with sorting mode */
/** Update revwalker with sorting mode. */
static void set_sorting(struct log_state *s, unsigned int sort_mode)
{
/* open repo on demand if it isn't already open */
/** Open repo on demand if it isn't already open. */
if (!s->repo) {
if (!s->repodir) s->repodir = ".";
check_lg2(git_repository_open_ext(&s->repo, s->repodir, 0, NULL),
"Could not open repository", s->repodir);
}
/* create revwalker on demand if it doesn't already exist */
/** Create revwalker on demand if it doesn't already exist. */
if (!s->walker)
check_lg2(git_revwalk_new(&s->walker, s->repo),
"Could not create revision walker", NULL);
......@@ -261,7 +263,7 @@ static void set_sorting(struct log_state *s, unsigned int sort_mode)
git_revwalk_sorting(s->walker, s->sorting);
}
/* helper to format a git_time value like Git */
/** Helper to format a git_time value like Git. */
static void print_time(const git_time *intime, const char *prefix)
{
char sign, out[32];
......@@ -288,7 +290,7 @@ static void print_time(const git_time *intime, const char *prefix)
printf("%s%s %c%02d%02d\n", prefix, out, sign, hours, minutes);
}
/* helper to print a commit object */
/** Helper to print a commit object. */
static void print_commit(git_commit *commit)
{
char buf[GIT_OID_HEXSZ + 1];
......@@ -323,7 +325,7 @@ static void print_commit(git_commit *commit)
printf("\n");
}
/* helper to find how many files in a commit changed from its nth parent */
/** Helper to find how many files in a commit changed from its nth parent. */
static int match_with_parent(git_commit *commit, int i, git_diff_options *opts)
{
git_commit *parent;
......@@ -349,7 +351,7 @@ static int match_with_parent(git_commit *commit, int i, git_diff_options *opts)
return ndeltas > 0;
}
/* print a usage message for the program */
/** Print a usage message for the program. */
static void usage(const char *message, const char *arg)
{
if (message && arg)
......@@ -360,7 +362,7 @@ static void usage(const char *message, const char *arg)
exit(1);
}
/* parse some log command line options */
/** Parse some log command line options. */
static int parse_options(
struct log_state *s, struct log_options *opt, int argc, char **argv)
{
......@@ -379,7 +381,8 @@ static int parse_options(
if (a[0] != '-') {
if (!add_revision(s, a))
s->revisions++;
else /* try failed revision parse as filename */
else
/** Try failed revision parse as filename. */
break;
} else if (!strcmp(a, "--")) {
++args.pos;
......@@ -392,15 +395,15 @@ static int parse_options(
else if (!strcmp(a, "--reverse"))
set_sorting(s, GIT_SORT_REVERSE);
else if (match_str_arg(&s->repodir, &args, "--git-dir"))
/* found git-dir */;
/** Found git-dir. */;
else if (match_int_arg(&opt->skip, &args, "--skip", 0))
/* found valid --skip */;
/** Found valid --skip. */;
else if (match_int_arg(&opt->limit, &args, "--max-count", 0))
/* found valid --max-count */;
/** Found valid --max-count. */;
else if (a[1] >= '0' && a[1] <= '9')
is_integer(&opt->limit, a + 1, 0);
else if (match_int_arg(&opt->limit, &args, "-n", 0))
/* found valid -n */;
/** Found valid -n. */;
else if (!strcmp(a, "--merges"))
opt->min_parents = 2;
else if (!strcmp(a, "--no-merges"))
......@@ -410,9 +413,9 @@ static int parse_options(
else if (!strcmp(a, "--no-max-parents"))
opt->max_parents = -1;
else if (match_int_arg(&opt->max_parents, &args, "--max-parents=", 1))
/* found valid --max-parents */;
/** Found valid --max-parents. */;
else if (match_int_arg(&opt->min_parents, &args, "--min-parents=", 0))
/* found valid --min_parents */;
/** Found valid --min_parents. */;
else if (!strcmp(a, "-p") || !strcmp(a, "-u") || !strcmp(a, "--patch"))
opt->show_diff = 1;
else
......
examples/rev-parse.c
......@@ -7,8 +7,7 @@
#include "common.h"
/* Forward declarations for helpers */
/** Forward declarations for helpers. */
struct parse_state {
git_repository *repo;
const char *repodir;
......
examples/status.c
......@@ -7,17 +7,19 @@
#include "common.h"
/*
/**
* This example demonstrates the use of the libgit2 status APIs,
* particularly the `git_status_list` object, to roughly simulate the
* output of running `git status`. It serves as a simple example of
* using those APIs to get basic status information.
*
* This does not have:
*
* - Robust error handling
* - Colorized or paginated output formatting
*
* This does have:
*
* - Examples of translating command line arguments to the status
* options settings to mimic `git status` results.
* - A sample status formatter that matches the default "long" format
......@@ -64,7 +66,7 @@ int main(int argc, char *argv[])
parse_opts(&o, argc, argv);
/*
/**
* Try to open the repository at the given path (or at the current
* directory if none was given).
*/
......@@ -75,7 +77,7 @@ int main(int argc, char *argv[])
fatal("Cannot report status on bare repository",
git_repository_path(repo));
/*
/**
* Run status on the repository
*
* Because we want to simluate a full "git status" run and want to
......@@ -140,7 +142,7 @@ static void print_long(git_repository *repo, git_status_list *status)
(void)repo;
/* print index changes */
/** Print index changes. */
for (i = 0; i < maxi; ++i) {
char *istatus = NULL;
......@@ -189,7 +191,7 @@ static void print_long(git_repository *repo, git_status_list *status)
}
header = 0;
/* print workdir changes to tracked files */
/** Print workdir changes to tracked files. */
for (i = 0; i < maxi; ++i) {
char *wstatus = NULL;
......@@ -234,7 +236,7 @@ static void print_long(git_repository *repo, git_status_list *status)
}
header = 0;
/* print untracked files */
/** Print untracked files. */
header = 0;
......@@ -256,7 +258,7 @@ static void print_long(git_repository *repo, git_status_list *status)
header = 0;
/* print ignored files */
/** Print ignored files. */
for (i = 0; i < maxi; ++i) {
s = git_status_byindex(status, i);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment