From 56c72b759c3adb92c0fdab18fccfb25fb561cd4f Mon Sep 17 00:00:00 2001 From: Russell Belfer Date: Mon, 17 Dec 2012 11:00:53 -0800 Subject: [PATCH 1/2] Fix diff constructor name order confusion The diff constructor functions had some confusing names, where the "old" side of the diff was coming after the "new" side. This reverses the order in the function name to make it less confusing. Specifically... * git_diff_index_to_tree becomes git_diff_tree_to_index * git_diff_workdir_to_index becomes git_diff_index_to_workdir * git_diff_workdir_to_tree becomes git_diff_tree_to_workdir --- examples/Makefile | 2 +- examples/diff.c | 14 ++++---- include/git2/diff.h | 65 ++++++++++++++++++++++++-------------- src/checkout.c | 2 +- src/diff.c | 6 ++-- src/stash.c | 6 ++-- src/status.c | 4 +-- src/submodule.c | 4 +-- tests-clar/diff/diffiter.c | 22 ++++++------- tests-clar/diff/index.c | 10 +++--- tests-clar/diff/workdir.c | 62 ++++++++++++++++++------------------ 11 files changed, 107 insertions(+), 90 deletions(-) diff --git a/examples/Makefile b/examples/Makefile index da4df5240..b306d4800 100644 --- a/examples/Makefile +++ b/examples/Makefile @@ -1,7 +1,7 @@ .PHONY: all CC = gcc -CFLAGS = -g -I../include -I../src -Wall -Wextra -Wmissing-prototypes +CFLAGS = -g -I../include -I../src -Wall -Wextra -Wmissing-prototypes -Wno-missing-field-initializers LFLAGS = -L../build -lgit2 -lz APPS = general showindex diff diff --git a/examples/diff.c b/examples/diff.c index b81a8682a..63956aa4e 100644 --- a/examples/diff.c +++ b/examples/diff.c @@ -110,12 +110,12 @@ static int check_uint16_param(const char *arg, const char *pattern, uint16_t *va return 1; } -static int check_str_param(const char *arg, const char *pattern, char **val) +static int check_str_param(const char *arg, const char *pattern, const char **val) { size_t len = strlen(pattern); if (strncmp(arg, pattern, len)) return 0; - *val = (char *)(arg + len); + *val = (const char *)(arg + len); return 1; } @@ -206,20 +206,20 @@ int main(int argc, char *argv[]) if (t1 && t2) check(git_diff_tree_to_tree(&diff, repo, t1, t2, &opts), "Diff"); else if (t1 && cached) - check(git_diff_index_to_tree(&diff, repo, t1, NULL, &opts), "Diff"); + check(git_diff_tree_to_index(&diff, repo, t1, NULL, &opts), "Diff"); else if (t1) { git_diff_list *diff2; - check(git_diff_index_to_tree(&diff, repo, t1, NULL, &opts), "Diff"); - check(git_diff_workdir_to_index(&diff2, repo, NULL, &opts), "Diff"); + check(git_diff_tree_to_index(&diff, repo, t1, NULL, &opts), "Diff"); + check(git_diff_index_to_workdir(&diff2, repo, NULL, &opts), "Diff"); check(git_diff_merge(diff, diff2), "Merge diffs"); git_diff_list_free(diff2); } else if (cached) { check(resolve_to_tree(repo, "HEAD", &t1), "looking up HEAD"); - check(git_diff_index_to_tree(&diff, repo, t1, NULL, &opts), "Diff"); + check(git_diff_tree_to_index(&diff, repo, t1, NULL, &opts), "Diff"); } else - check(git_diff_workdir_to_index(&diff, repo, NULL, &opts), "Diff"); + check(git_diff_index_to_workdir(&diff, repo, NULL, &opts), "Diff"); if (color >= 0) fputs(colors[0], stdout); diff --git a/include/git2/diff.h b/include/git2/diff.h index 49f781ddd..f1db90d80 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -227,15 +227,21 @@ typedef struct { /** * Description of changes to one file. * - * When iterating over a diff list object, this will generally be passed to - * most callback functions and you can use the contents to understand - * exactly what has changed. + * The `old_file` repesents the "from" side of the diff and the `new_file` + * repesents to "to" side of the diff. What those means depend on the + * function that was used to generate the diff and will be documented below. + * You can also use the `GIT_DIFF_REVERSE` flag to flip it around. * - * Under some circumstances, not all fields will be filled in, but the code - * generally tries to fill in as much as possible. One example is that the - * "binary" field will not actually look at file contents if you do not - * pass in hunk and/or line callbacks to the diff foreach iteration function. - * It will just use the git attributes for those files. + * Although the two sides of the delta are named "old_file" and "new_file", + * they actually may correspond to entries that represent a file, a symbolic + * link, a submodule commit id, or even a tree (if you are tracking type + * changes or ignored/untracked directories). + * + * Under some circumstances, in the name of efficiency, not all fields will + * be filled in, but we generally try to fill in as much as possible. One + * example is that the "binary" field will not examine file contents if you + * do not pass in hunk and/or line callbacks to the diff foreach iteration + * function. It will just use the git attributes for those files. */ typedef struct { git_diff_file old_file; @@ -381,9 +387,12 @@ typedef struct { GIT_EXTERN(void) git_diff_list_free(git_diff_list *diff); /** - * Compute a difference between two tree objects. + * Create a diff list with the difference between two tree objects. * - * This is equivalent to `git diff ` + * This is equivalent to `git diff ` + * + * The first tree will be used for the "old_file" side of the delta and the + * second tree will be used for the "new_file" side of the delta. * * @param diff Output pointer to a git_diff_list pointer to be allocated. * @param repo The repository containing the trees. @@ -399,18 +408,21 @@ GIT_EXTERN(int) git_diff_tree_to_tree( const git_diff_options *opts); /**< can be NULL for defaults */ /** - * Compute a difference between a tree and the repository index. + * Create a diff list between a tree and repository index. * * This is equivalent to `git diff --cached ` or if you pass * the HEAD tree, then like `git diff --cached`. * + * The tree you pass will be used for the "old_file" side of the delta, and + * the index will be used for the "new_file" side of the delta. + * * @param diff Output pointer to a git_diff_list pointer to be allocated. * @param repo The repository containing the tree and index. * @param old_tree A git_tree object to diff from. * @param index The index to diff with; repo index used if NULL. * @param opts Structure with options to influence diff or NULL for defaults. */ -GIT_EXTERN(int) git_diff_index_to_tree( +GIT_EXTERN(int) git_diff_tree_to_index( git_diff_list **diff, git_repository *repo, git_tree *old_tree, @@ -418,40 +430,45 @@ GIT_EXTERN(int) git_diff_index_to_tree( const git_diff_options *opts); /**< can be NULL for defaults */ /** - * Compute a difference between the working directory and the repository index. + * Create a diff list between the repository index and the workdir directory. * * This matches the `git diff` command. See the note below on - * `git_diff_workdir_to_tree` for a discussion of the difference between + * `git_diff_tree_to_workdir` for a discussion of the difference between * `git diff` and `git diff HEAD` and how to emulate a `git diff ` * using libgit2. * + * The index will be used for the "old_file" side of the delta, and the + * working directory will be used for the "new_file" side of the delta. + * * @param diff Output pointer to a git_diff_list pointer to be allocated. * @param repo The repository. * @param index The index to diff from; repo index used if NULL. * @param opts Structure with options to influence diff or NULL for defaults. */ -GIT_EXTERN(int) git_diff_workdir_to_index( +GIT_EXTERN(int) git_diff_index_to_workdir( git_diff_list **diff, git_repository *repo, git_index *index, const git_diff_options *opts); /**< can be NULL for defaults */ /** - * Compute a difference between the working directory and a tree. + * Create a diff list between a tree and the working directory. * - * This is *NOT* the same as `git diff `. Running `git diff HEAD` - * or the like actually uses information from the index, along with the tree - * and workdir dir info. + * The tree you provide will be used for the "old_file" side of the delta, + * and the working directory will be used for the "new_file" side. + * + * Please note: this is *NOT* the same as `git diff `. Running + * `git diff HEAD` or the like actually uses information from the index, + * along with the tree and working directory info. * * This function returns strictly the differences between the tree and the * files contained in the working directory, regardless of the state of * files in the index. It may come as a surprise, but there is no direct * equivalent in core git. * - * To emulate `git diff `, you should call both - * `git_diff_index_to_tree` and `git_diff_workdir_to_index`, then call - * `git_diff_merge` on the results. That will yield a `git_diff_list` that - * matches the git output. + * To emulate `git diff `, call both `git_diff_tree_to_index` and + * `git_diff_index_to_workdir`, then call `git_diff_merge` on the results. + * That will yield a `git_diff_list` that matches the git output. * * If this seems confusing, take the case of a file with a staged deletion * where the file has then been put back into the working dir and modified. @@ -463,7 +480,7 @@ GIT_EXTERN(int) git_diff_workdir_to_index( * @param old_tree A git_tree object to diff from. * @param opts Structure with options to influence diff or NULL for defaults. */ -GIT_EXTERN(int) git_diff_workdir_to_tree( +GIT_EXTERN(int) git_diff_tree_to_workdir( git_diff_list **diff, git_repository *repo, git_tree *old_tree, diff --git a/src/checkout.c b/src/checkout.c index d9f0f8fad..972366fbb 100644 --- a/src/checkout.c +++ b/src/checkout.c @@ -632,7 +632,7 @@ int git_checkout_index( if (opts && opts->paths.count > 0) diff_opts.pathspec = opts->paths; - if ((error = git_diff_workdir_to_index(&diff, repo, index, &diff_opts)) < 0) + if ((error = git_diff_index_to_workdir(&diff, repo, index, &diff_opts)) < 0) goto cleanup; if ((error = git_buf_puts(&workdir, git_repository_workdir(repo))) < 0) diff --git a/src/diff.c b/src/diff.c index 822ae5b09..9c0b45f8e 100644 --- a/src/diff.c +++ b/src/diff.c @@ -784,7 +784,7 @@ int git_diff_tree_to_tree( return error; } -int git_diff_index_to_tree( +int git_diff_tree_to_index( git_diff_list **diff, git_repository *repo, git_tree *old_tree, @@ -806,7 +806,7 @@ int git_diff_index_to_tree( return error; } -int git_diff_workdir_to_index( +int git_diff_index_to_workdir( git_diff_list **diff, git_repository *repo, git_index *index, @@ -828,7 +828,7 @@ int git_diff_workdir_to_index( } -int git_diff_workdir_to_tree( +int git_diff_tree_to_workdir( git_diff_list **diff, git_repository *repo, git_tree *old_tree, diff --git a/src/stash.c b/src/stash.c index e32d8fa31..705fc75ea 100644 --- a/src/stash.c +++ b/src/stash.c @@ -251,7 +251,7 @@ static int build_untracked_tree( if (git_commit_tree(&i_tree, i_commit) < 0) goto cleanup; - if (git_diff_workdir_to_tree(&diff, git_index_owner(index), i_tree, &opts) < 0) + if (git_diff_tree_to_workdir(&diff, git_index_owner(index), i_tree, &opts) < 0) goto cleanup; if (git_diff_foreach(diff, update_index_cb, NULL, NULL, &data) < 0) @@ -323,10 +323,10 @@ static int build_workdir_tree( if (git_commit_tree(&b_tree, b_commit) < 0) goto cleanup; - if (git_diff_index_to_tree(&diff, repo, b_tree, NULL, &opts) < 0) + if (git_diff_tree_to_index(&diff, repo, b_tree, NULL, &opts) < 0) goto cleanup; - if (git_diff_workdir_to_index(&diff2, repo, NULL, &opts) < 0) + if (git_diff_index_to_workdir(&diff2, repo, NULL, &opts) < 0) goto cleanup; if (git_diff_merge(diff, diff2) < 0) diff --git a/src/status.c b/src/status.c index 1ad835adb..115217c49 100644 --- a/src/status.c +++ b/src/status.c @@ -145,11 +145,11 @@ int git_status_foreach_ext( /* TODO: support EXCLUDE_SUBMODULES flag */ if (show != GIT_STATUS_SHOW_WORKDIR_ONLY && - (err = git_diff_index_to_tree(&idx2head, repo, head, NULL, &diffopt)) < 0) + (err = git_diff_tree_to_index(&idx2head, repo, head, NULL, &diffopt)) < 0) goto cleanup; if (show != GIT_STATUS_SHOW_INDEX_ONLY && - (err = git_diff_workdir_to_index(&wd2idx, repo, NULL, &diffopt)) < 0) + (err = git_diff_index_to_workdir(&wd2idx, repo, NULL, &diffopt)) < 0) goto cleanup; usercb.cb = cb; diff --git a/src/submodule.c b/src/submodule.c index 3d9950d58..94b4f724e 100644 --- a/src/submodule.c +++ b/src/submodule.c @@ -1454,7 +1454,7 @@ static int submodule_wd_status(unsigned int *status, git_submodule *sm) if (sm->ignore == GIT_SUBMODULE_IGNORE_NONE) opt.flags |= GIT_DIFF_INCLUDE_UNTRACKED; - error = git_diff_index_to_tree(&diff, sm_repo, sm_head, NULL, &opt); + error = git_diff_tree_to_index(&diff, sm_repo, sm_head, NULL, &opt); if (!error) { if (git_diff_num_deltas(diff) > 0) @@ -1471,7 +1471,7 @@ static int submodule_wd_status(unsigned int *status, git_submodule *sm) /* perform index-to-workdir diff on submodule */ - error = git_diff_workdir_to_index(&diff, sm_repo, NULL, &opt); + error = git_diff_index_to_workdir(&diff, sm_repo, NULL, &opt); if (!error) { size_t untracked = diff --git a/tests-clar/diff/diffiter.c b/tests-clar/diff/diffiter.c index 306a13eb9..8d550ec0f 100644 --- a/tests-clar/diff/diffiter.c +++ b/tests-clar/diff/diffiter.c @@ -16,7 +16,7 @@ void test_diff_diffiter__create(void) git_diff_list *diff; size_t d, num_d; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, NULL)); num_d = git_diff_num_deltas(diff); for (d = 0; d < num_d; ++d) { @@ -34,7 +34,7 @@ void test_diff_diffiter__iterate_files(void) size_t d, num_d; int count = 0; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, NULL)); num_d = git_diff_num_deltas(diff); cl_assert_equal_i(6, (int)num_d); @@ -57,7 +57,7 @@ void test_diff_diffiter__iterate_files_2(void) size_t d, num_d; int count = 0; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, NULL)); num_d = git_diff_num_deltas(diff); cl_assert_equal_i(8, (int)num_d); @@ -85,7 +85,7 @@ void test_diff_diffiter__iterate_files_and_hunks(void) opts.interhunk_lines = 1; opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, &opts)); num_d = git_diff_num_deltas(diff); @@ -138,7 +138,7 @@ void test_diff_diffiter__max_size_threshold(void) opts.interhunk_lines = 1; opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, &opts)); num_d = git_diff_num_deltas(diff); for (d = 0; d < num_d; ++d) { @@ -173,7 +173,7 @@ void test_diff_diffiter__max_size_threshold(void) opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; opts.max_size = 50; /* treat anything over 50 bytes as binary! */ - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, &opts)); num_d = git_diff_num_deltas(diff); for (d = 0; d < num_d; ++d) { @@ -216,7 +216,7 @@ void test_diff_diffiter__iterate_all(void) opts.interhunk_lines = 1; opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, &opts)); num_d = git_diff_num_deltas(diff); for (d = 0; d < num_d; ++d) { @@ -292,7 +292,7 @@ void test_diff_diffiter__iterate_randomly_while_saving_state(void) opts.interhunk_lines = 1; opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, &opts)); num_d = git_diff_num_deltas(diff); @@ -419,7 +419,7 @@ void test_diff_diffiter__iterate_and_generate_patch_text(void) git_diff_list *diff; size_t d, num_d; - cl_git_pass(git_diff_workdir_to_index(&diff, repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, repo, NULL, NULL)); num_d = git_diff_num_deltas(diff); cl_assert_equal_i(8, (int)num_d); @@ -452,13 +452,13 @@ void test_diff_diffiter__checks_options_version(void) opts.version = 0; opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; - cl_git_fail(git_diff_workdir_to_index(&diff, repo, NULL, &opts)); + cl_git_fail(git_diff_index_to_workdir(&diff, repo, NULL, &opts)); err = giterr_last(); cl_assert_equal_i(GITERR_INVALID, err->klass); giterr_clear(); opts.version = 1024; - cl_git_fail(git_diff_workdir_to_index(&diff, repo, NULL, &opts)); + cl_git_fail(git_diff_index_to_workdir(&diff, repo, NULL, &opts)); err = giterr_last(); cl_assert_equal_i(GITERR_INVALID, err->klass); } diff --git a/tests-clar/diff/index.c b/tests-clar/diff/index.c index 267b3291c..41941ee28 100644 --- a/tests-clar/diff/index.c +++ b/tests-clar/diff/index.c @@ -32,7 +32,7 @@ void test_diff_index__0(void) memset(&exp, 0, sizeof(exp)); - cl_git_pass(git_diff_index_to_tree(&diff, g_repo, a, NULL, &opts)); + cl_git_pass(git_diff_tree_to_index(&diff, g_repo, a, NULL, &opts)); cl_git_pass(git_diff_foreach( diff, diff_file_cb, diff_hunk_cb, diff_line_cb, &exp)); @@ -60,7 +60,7 @@ void test_diff_index__0(void) diff = NULL; memset(&exp, 0, sizeof(exp)); - cl_git_pass(git_diff_index_to_tree(&diff, g_repo, b, NULL, &opts)); + cl_git_pass(git_diff_tree_to_index(&diff, g_repo, b, NULL, &opts)); cl_git_pass(git_diff_foreach( diff, diff_file_cb, diff_hunk_cb, diff_line_cb, &exp)); @@ -125,7 +125,7 @@ void test_diff_index__1(void) memset(&exp, 0, sizeof(exp)); - cl_git_pass(git_diff_index_to_tree(&diff, g_repo, a, NULL, &opts)); + cl_git_pass(git_diff_tree_to_index(&diff, g_repo, a, NULL, &opts)); cl_assert_equal_i( GIT_EUSER, @@ -150,13 +150,13 @@ void test_diff_index__checks_options_version(void) const git_error *err; opts.version = 0; - cl_git_fail(git_diff_index_to_tree(&diff, g_repo, a, NULL, &opts)); + cl_git_fail(git_diff_tree_to_index(&diff, g_repo, a, NULL, &opts)); err = giterr_last(); cl_assert_equal_i(GITERR_INVALID, err->klass); giterr_clear(); opts.version = 1024; - cl_git_fail(git_diff_index_to_tree(&diff, g_repo, a, NULL, &opts)); + cl_git_fail(git_diff_tree_to_index(&diff, g_repo, a, NULL, &opts)); err = giterr_last(); cl_assert_equal_i(GITERR_INVALID, err->klass); } diff --git a/tests-clar/diff/workdir.c b/tests-clar/diff/workdir.c index 10d58b118..1b1b616a4 100644 --- a/tests-clar/diff/workdir.c +++ b/tests-clar/diff/workdir.c @@ -26,7 +26,7 @@ void test_diff_workdir__to_index(void) opts.interhunk_lines = 1; opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -84,7 +84,7 @@ void test_diff_workdir__to_tree(void) opts.interhunk_lines = 1; opts.flags |= GIT_DIFF_INCLUDE_IGNORED | GIT_DIFF_INCLUDE_UNTRACKED; - /* You can't really generate the equivalent of git_diff_workdir_to_tree() + /* You can't really generate the equivalent of git_diff_tree_to_workdir() * using C git. It really wants to interpose the index into the diff. * * To validate the following results with command line git, I ran the @@ -94,7 +94,7 @@ void test_diff_workdir__to_tree(void) * The results are documented at the bottom of this file in the * long comment entitled "PREPARATION OF TEST DATA". */ - cl_git_pass(git_diff_workdir_to_tree(&diff, g_repo, a, &opts)); + cl_git_pass(git_diff_tree_to_workdir(&diff, g_repo, a, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -127,8 +127,8 @@ void test_diff_workdir__to_tree(void) * a workdir to tree diff (even though it is not really). This is what * you would get from "git diff --name-status 26a125ee1bf" */ - cl_git_pass(git_diff_index_to_tree(&diff, g_repo, a, NULL, &opts)); - cl_git_pass(git_diff_workdir_to_index(&diff2, g_repo, NULL, &opts)); + cl_git_pass(git_diff_tree_to_index(&diff, g_repo, a, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff2, g_repo, NULL, &opts)); cl_git_pass(git_diff_merge(diff, diff2)); git_diff_list_free(diff2); @@ -164,8 +164,8 @@ void test_diff_workdir__to_tree(void) /* Again, emulating "git diff " for testing purposes using * "git diff --name-status 0017bd4ab1ec3" instead. */ - cl_git_pass(git_diff_index_to_tree(&diff, g_repo, b, NULL, &opts)); - cl_git_pass(git_diff_workdir_to_index(&diff2, g_repo, NULL, &opts)); + cl_git_pass(git_diff_tree_to_index(&diff, g_repo, b, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff2, g_repo, NULL, &opts)); cl_git_pass(git_diff_merge(diff, diff2)); git_diff_list_free(diff2); @@ -216,7 +216,7 @@ void test_diff_workdir__to_index_with_pathspec(void) opts.pathspec.strings = &pathspec; opts.pathspec.count = 1; - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -239,7 +239,7 @@ void test_diff_workdir__to_index_with_pathspec(void) pathspec = "modified_file"; - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -262,7 +262,7 @@ void test_diff_workdir__to_index_with_pathspec(void) pathspec = "subdir"; - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -285,7 +285,7 @@ void test_diff_workdir__to_index_with_pathspec(void) pathspec = "*_deleted"; - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -324,7 +324,7 @@ void test_diff_workdir__filemode_changes(void) /* test once with no mods */ - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, NULL)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -347,7 +347,7 @@ void test_diff_workdir__filemode_changes(void) cl_assert(cl_toggle_filemode("issue_592/a.txt")); - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, NULL)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -386,7 +386,7 @@ void test_diff_workdir__filemode_changes_with_filemode_false(void) /* test once with no mods */ - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, NULL)); memset(&exp, 0, sizeof(exp)); cl_git_pass(git_diff_foreach( @@ -402,7 +402,7 @@ void test_diff_workdir__filemode_changes_with_filemode_false(void) cl_assert(cl_toggle_filemode("issue_592/a.txt")); - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, NULL)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, NULL)); memset(&exp, 0, sizeof(exp)); cl_git_pass(git_diff_foreach( @@ -442,8 +442,8 @@ void test_diff_workdir__head_index_and_workdir_all_differ(void) opts.pathspec.strings = &pathspec; opts.pathspec.count = 1; - cl_git_pass(git_diff_index_to_tree(&diff_i2t, g_repo, tree, NULL, &opts)); - cl_git_pass(git_diff_workdir_to_index(&diff_w2i, g_repo, NULL, &opts)); + cl_git_pass(git_diff_tree_to_index(&diff_i2t, g_repo, tree, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff_w2i, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -529,7 +529,7 @@ void test_diff_workdir__eof_newline_changes(void) opts.pathspec.strings = &pathspec; opts.pathspec.count = 1; - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -556,7 +556,7 @@ void test_diff_workdir__eof_newline_changes(void) cl_git_append2file("status/current_file", "\n"); - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -583,7 +583,7 @@ void test_diff_workdir__eof_newline_changes(void) cl_git_rewritefile("status/current_file", "current_file"); - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); for (use_iterator = 0; use_iterator <= 1; use_iterator++) { memset(&exp, 0, sizeof(exp)); @@ -611,7 +611,7 @@ void test_diff_workdir__eof_newline_changes(void) /* PREPARATION OF TEST DATA * - * Since there is no command line equivalent of git_diff_workdir_to_tree, + * Since there is no command line equivalent of git_diff_tree_to_workdir, * it was a bit of a pain to confirm that I was getting the expected * results in the first part of this tests. Here is what I ended up * doing to set my expectation for the file counts and results: @@ -699,13 +699,13 @@ void test_diff_workdir__larger_hunks(void) /* okay, this is a bit silly, but oh well */ switch (i) { case 0: - cl_git_pass(git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); break; case 1: - cl_git_pass(git_diff_workdir_to_tree(&diff, g_repo, a, &opts)); + cl_git_pass(git_diff_tree_to_workdir(&diff, g_repo, a, &opts)); break; case 2: - cl_git_pass(git_diff_workdir_to_tree(&diff, g_repo, b, &opts)); + cl_git_pass(git_diff_tree_to_workdir(&diff, g_repo, b, &opts)); break; } @@ -748,7 +748,7 @@ void test_diff_workdir__larger_hunks(void) /* Set up a test that exercises this code. The easiest test using existing * test data is probably to create a sandbox of submod2 and then run a - * git_diff_workdir_to_tree against tree + * git_diff_tree_to_workdir against tree * 873585b94bdeabccea991ea5e3ec1a277895b698. As for what you should actually * test, you can start by just checking that the number of lines of diff * content matches the actual output of git diff. That will at least @@ -784,7 +784,7 @@ void test_diff_workdir__submodules(void) GIT_DIFF_RECURSE_UNTRACKED_DIRS | GIT_DIFF_INCLUDE_UNTRACKED_CONTENT; - cl_git_pass(git_diff_workdir_to_tree(&diff, g_repo, a, &opts)); + cl_git_pass(git_diff_tree_to_workdir(&diff, g_repo, a, &opts)); /* diff_print(stderr, diff); */ @@ -829,12 +829,12 @@ void test_diff_workdir__cannot_diff_against_a_bare_repository(void) g_repo = cl_git_sandbox_init("testrepo.git"); cl_assert_equal_i( - GIT_EBAREREPO, git_diff_workdir_to_index(&diff, g_repo, NULL, &opts)); + GIT_EBAREREPO, git_diff_index_to_workdir(&diff, g_repo, NULL, &opts)); cl_git_pass(git_repository_head_tree(&tree, g_repo)); cl_assert_equal_i( - GIT_EBAREREPO, git_diff_workdir_to_tree(&diff, g_repo, tree, &opts)); + GIT_EBAREREPO, git_diff_tree_to_workdir(&diff, g_repo, tree, &opts)); git_tree_free(tree); } @@ -850,7 +850,7 @@ void test_diff_workdir__to_null_tree(void) g_repo = cl_git_sandbox_init("status"); - cl_git_pass(git_diff_workdir_to_tree(&diff, g_repo, NULL, &opts)); + cl_git_pass(git_diff_tree_to_workdir(&diff, g_repo, NULL, &opts)); memset(&exp, 0, sizeof(exp)); @@ -871,13 +871,13 @@ void test_diff_workdir__checks_options_version(void) g_repo = cl_git_sandbox_init("status"); opts.version = 0; - cl_git_fail(git_diff_workdir_to_tree(&diff, g_repo, NULL, &opts)); + cl_git_fail(git_diff_tree_to_workdir(&diff, g_repo, NULL, &opts)); err = giterr_last(); cl_assert_equal_i(GITERR_INVALID, err->klass); giterr_clear(); opts.version = 1024; - cl_git_fail(git_diff_workdir_to_tree(&diff, g_repo, NULL, &opts)); + cl_git_fail(git_diff_tree_to_workdir(&diff, g_repo, NULL, &opts)); err = giterr_last(); cl_assert_equal_i(GITERR_INVALID, err->klass); } From ba084f7aaf431f96588b13551ebfdffdd3eb44dc Mon Sep 17 00:00:00 2001 From: Russell Belfer Date: Mon, 17 Dec 2012 11:03:42 -0800 Subject: [PATCH 2/2] More diff.h comment fixes Based on feedback from the ObjectiveGit folks, these are some further updates to diff.h areas that are poorly documented. --- include/git2/diff.h | 86 +++++++++++++++++++++++++++------------------ 1 file changed, 52 insertions(+), 34 deletions(-) diff --git a/include/git2/diff.h b/include/git2/diff.h index f1db90d80..b26dd4214 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -139,7 +139,8 @@ typedef enum { * - `new_prefix` is the virtual "directory" to prefix to new file names * in hunk headers (default "b") * - `pathspec` is an array of paths / fnmatch patterns to constrain diff - * - `max_size` is a file size above which a blob will be marked as binary + * - `max_size` is a file size (in bytes) above which a blob will be marked + * as binary automatically; pass a negative value to disable. */ typedef struct { unsigned int version; /**< version for the struct */ @@ -148,8 +149,8 @@ typedef struct { uint16_t interhunk_lines; /**< defaults to 0 */ const char *old_prefix; /**< defaults to "a" */ const char *new_prefix; /**< defaults to "b" */ - git_strarray pathspec; /**< defaults to show all paths */ - git_off_t max_size; /**< defaults to 512mb */ + git_strarray pathspec; /**< defaults to include all paths */ + git_off_t max_size; /**< defaults to 512MB */ } git_diff_options; #define GIT_DIFF_OPTIONS_VERSION 1 @@ -157,14 +158,19 @@ typedef struct { /** * The diff list object that contains all individual file deltas. + * + * This is an opaque structure which will be allocated by one of the diff + * generator functions below (such as `git_diff_tree_to_tree`). You are + * responsible for releasing the object memory when done, using the + * `git_diff_list_free()` function. */ typedef struct git_diff_list git_diff_list; /** - * Flags that can be set for the file on side of a diff. + * Flags for the file object on each side of a diff. * - * Most of the flags are just for internal consumption by libgit2, - * but some of them may be interesting to external users. + * Note: most of these flags are just for **internal** consumption by + * libgit2, but some of them may be interesting to external users. */ typedef enum { GIT_DIFF_FILE_VALID_OID = (1 << 0), /** `oid` value is known correct */ @@ -187,34 +193,38 @@ typedef enum { * DELETED pairs). */ typedef enum { - GIT_DELTA_UNMODIFIED = 0, - GIT_DELTA_ADDED = 1, - GIT_DELTA_DELETED = 2, - GIT_DELTA_MODIFIED = 3, - GIT_DELTA_RENAMED = 4, - GIT_DELTA_COPIED = 5, - GIT_DELTA_IGNORED = 6, - GIT_DELTA_UNTRACKED = 7, - GIT_DELTA_TYPECHANGE = 8, + GIT_DELTA_UNMODIFIED = 0, /** no changes */ + GIT_DELTA_ADDED = 1, /** entry does not exist in old version */ + GIT_DELTA_DELETED = 2, /** entry does not exist in new version */ + GIT_DELTA_MODIFIED = 3, /** entry content changed between old and new */ + GIT_DELTA_RENAMED = 4, /** entry was renamed between old and new */ + GIT_DELTA_COPIED = 5, /** entry was copied from another old entry */ + GIT_DELTA_IGNORED = 6, /** entry is ignored item in workdir */ + GIT_DELTA_UNTRACKED = 7, /** entry is untracked item in workdir */ + GIT_DELTA_TYPECHANGE = 8, /** type of entry changed between old and new */ } git_delta_t; /** - * Description of one side of a diff. + * Description of one side of a diff entry. * - * The `oid` is the `git_oid` of the item. If it represents an absent side - * of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta), then the - * oid will be zeroes. + * Although this is called a "file", it may actually represent a file, a + * symbolic link, a submodule commit id, or even a tree (although that only + * if you are tracking type changes or ignored/untracked directories). * - * `path` is the NUL-terminated path to the file relative to the working + * The `oid` is the `git_oid` of the item. If the entry represents an + * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta), + * then the oid will be zeroes. + * + * `path` is the NUL-terminated path to the entry relative to the working * directory of the repository. * - * `size` is the size of the file in bytes. + * `size` is the size of the entry in bytes. * * `flags` is a combination of the `git_diff_file_flag_t` types, but those * are largely internal values. * - * `mode` is, roughly, the stat() st_mode value for the item. This will be - * restricted to one of the `git_filemode_t` values. + * `mode` is, roughly, the stat() `st_mode` value for the item. This will + * be restricted to one of the `git_filemode_t` values. */ typedef struct { git_oid oid; @@ -225,7 +235,11 @@ typedef struct { } git_diff_file; /** - * Description of changes to one file. + * Description of changes to one entry. + * + * When iterating over a diff list object, this will be passed to most + * callback functions and you can use the contents to understand exactly + * what has changed. * * The `old_file` repesents the "from" side of the diff and the `new_file` * repesents to "to" side of the diff. What those means depend on the @@ -253,6 +267,10 @@ typedef struct { /** * When iterating over a diff, callback that will be made per file. + * + * @param delta A pointer to the delta data for the file + * @param progress Goes from 0 to 1 over the diff list + * @param payload User-specified pointer from foreach function */ typedef int (*git_diff_file_cb)( const git_diff_delta *delta, @@ -263,10 +281,10 @@ typedef int (*git_diff_file_cb)( * Structure describing a hunk of a diff. */ typedef struct { - int old_start; - int old_lines; - int new_start; - int new_lines; + int old_start; /** Starting line number in old_file */ + int old_lines; /** Number of lines in old_file */ + int new_start; /** Starting line number in new_file */ + int new_lines; /** Number of lines in new_file */ } git_diff_range; /** @@ -314,12 +332,12 @@ typedef enum { * of lines of file and hunk headers. */ typedef int (*git_diff_data_cb)( - const git_diff_delta *delta, - const git_diff_range *range, - char line_origin, /**< GIT_DIFF_LINE_... value from above */ - const char *content, - size_t content_len, - void *payload); + const git_diff_delta *delta, /** delta that contains this data */ + const git_diff_range *range, /** range of lines containing this data */ + char line_origin, /** git_diff_list_t value from above */ + const char *content, /** diff data - not NUL terminated */ + size_t content_len, /** number of bytes of diff data */ + void *payload); /** user reference data */ /** * The diff patch is used to store all the text diffs for a delta.