mirror of
https://git.proxmox.com/git/libgit2
synced 2025-05-02 16:20:01 +00:00
Format comments for use with docco
This commit is contained in:
Ben Straub
parent
dbdb22b330
commit
85c6730ce8
@ -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];
|
||||
|
||||
@ -1,4 +1,13 @@
|
||||
/*
|
||||
* 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];
|
||||
|
||||
@ -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
|
||||
|
||||
@ -7,8 +7,7 @@
|
||||
|
||||
#include "common.h"
|
||||
|
||||
|
||||
/* Forward declarations for helpers */
|
||||
/** Forward declarations for helpers. */
|
||||
struct parse_state {
|
||||
git_repository *repo;
|
||||
const char *repodir;
|
||||
|
||||
@ -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);
|
||||
|
||||
Loading…
Reference in New Issue
Block a user