Skip to content

Commit f9ae763

Browse files
benben
committed
Merge pull request libgit2#38 from libgit2/index
101 samples: Index
2 parents 330134a + 15bff63 commit f9ae763

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎docs/guides/101-samples/index.md

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -797,6 +797,179 @@ int error = git_tag_peel(&dereferenced_target, tag);
797797
)
798798

799799

800+
<h2 id="index">Index</h2>
801+
802+
<h3 id="index_loading">Loading</h3>
803+
804+
```c
805+
/* Each repository owns an index */
806+
git_index *idx = NULL;
807+
int error = git_repository_index(&idx, repo);
808+
809+
/* Or you can open it by path */
810+
error = git_index_open(&idx, "/path/to/repo/.git/index");
811+
```
812+
813+
(
814+
[`git_repository_index`](http://libgit2.github.com/libgit2/#HEAD/group/repository/git_repository_index),
815+
[`git_index_open`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_open)
816+
)
817+
818+
<h3 id="index_creating">Creating (in-memory)</h3>
819+
820+
In-memory indexes cannot be saved to disk, but can be useful for creating trees.
821+
822+
```c
823+
git_index *idx = NULL;
824+
int error = git_index_new(&idx);
825+
```
826+
827+
(
828+
[`git_index_new`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_new)
829+
)
830+
831+
<h3 id="index_disk">Disk</h3>
832+
833+
```c
834+
/* Make the in-memory index match what's on disk */
835+
int error = git_index_read(idx, true);
836+
837+
/* Write the in-memory index to disk */
838+
error = git_index_write(idx);
839+
```
840+
841+
(
842+
[`git_index_read`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_read),
843+
[`git_index_write`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_write)
844+
)
845+
846+
<h3 id="index_trees">Trees</h3>
847+
848+
Note that all tree operations work recursively.
849+
For example, `git_index_read_tree` will replace not only the root directory, but all subdirectory contents as well.
850+
851+
```c
852+
/* Overwrite the index contents with those of a tree */
853+
git_tree *tree = NULL;
854+
int error = git_revparse_single((git_object**)&tree,
855+
repo, "HEAD~^{tree}");
856+
error = git_index_read_tree(idx, tree);
857+
858+
/* Write the index contents to the ODB as a tree */
859+
git_oid new_tree_id = {{0}};
860+
error = git_index_write_tree(&new_tree_id, idx);
861+
862+
/* In-memory indexes can write trees to any repo */
863+
error = git_index_write_tree_to(&new_tree_id, idx, other_repo);
864+
```
865+
866+
(
867+
[`git_revparse_single`](http://libgit2.github.com/libgit2/#HEAD/group/revparse/git_revparse_single),
868+
[`git_index_read_tree`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_read_tree),
869+
[`git_index_write_tree`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_write_tree),
870+
[`git_index_write_tree_to`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_write_tree_to)
871+
)
872+
873+
<h3 id="index_entries">Entries</h3>
874+
875+
```c
876+
/* Access by index */
877+
size_t count = git_index_entrycount(idx);
878+
for (size_t i=0; i<count; i++) {
879+
const git_index_entry *entry = git_index_get_byindex(idx, i);
880+
/* … */
881+
}
882+
883+
/* Access by path */
884+
const git_index_entry *entry = git_index_get_bypath(
885+
idx, /* index */
886+
"path/to/file.rb", /* path */
887+
0); /* stage */
888+
```
889+
890+
(
891+
[`git_index_entrycount`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_entrycount),
892+
[`git_index_get_byindex`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_get_byindex),
893+
[`git_index_get_bypath`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_get_bypath),
894+
[`git_index_entry`](http://libgit2.github.com/libgit2/#HEAD/type/git_index_entry)
895+
)
896+
897+
<h3 id="index_conflicts">Conflicts</h3>
898+
899+
```c
900+
if (git_index_has_conflicts(idx)) {
901+
/* If you know the path of a conflicted file */
902+
const git_index_entry *ancestor = NULL,
903+
*ours = NULL,
904+
*theirs = NULL;
905+
int error = git_index_conflict_get(&ancestor, &ours, &theirs
906+
idx, "path/to/file.cs");
907+
908+
/* Or, iterate through all conflicts */
909+
git_index_conflict_iterator *iter = NULL;
910+
error = git_index_conflict_iterator_new(&iter, idx);
911+
while (git_index_conflict_next(&ancestor, &ours, &theirs, iter)
912+
!= GIT_ITEROVER) {
913+
/* Mark this conflict as resolved */
914+
error = git_index_conflict_remove(idx, ours->path);
915+
}
916+
git_index_conflict_iterator_free(iter);
917+
}
918+
```
919+
920+
(
921+
[`git_index_has_conflicts`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_has_conflicts),
922+
[`git_index_conflict_get`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_get),
923+
[`git_index_conflict_iterator_new`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_iterator_new),
924+
[`git_index_conflict_next`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_next),
925+
[`git_index_conflict_iterator_free`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_iterator_free),
926+
[`git_index_conflict_remove`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_remove)
927+
)
928+
929+
<h3 id="index_add">Add & Remove</h3>
930+
931+
```c
932+
/* Force a single file to be added (even if it is ignored) */
933+
error = git_index_add_bypath(idx, "path/to/file.py");
934+
/* … or removed */
935+
error = git_index_remove_bypath(idx, "path/to/file.py");
936+
937+
typedef struct { /* … */ } match_data;
938+
int match_cb(const char *path, const char *spec, void *payload)
939+
{
940+
match_data *d = (match_data*)payload;
941+
/*
942+
* return 0 to add/remove this path,
943+
* a positive number to skip this path,
944+
* or a negative number to abort the operation.
945+
*/
946+
}
947+
948+
const char *paths[] = {"src/*", "test/*"};
949+
git_strarray arr = {paths, 2};
950+
951+
/* Add matching files (this skips ignored files) */
952+
match_data d = {0};
953+
int error = git_index_add_all(idx, &arr, GIT_INDEX_ADD_DEFAULT,
954+
match_cb, &d);
955+
/* … or remove them */
956+
error = git_index_remove_all(idx, &arr, match_cb, &d);
957+
958+
/* Something like 'git add .' */
959+
error = git_index_update_all(idx, &arr, match_cb, &d);
960+
```
961+
962+
(
963+
[`git_index_add_bypath`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_add_bypath),
964+
[`git_index_remove_bypath`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_remove_bypath),
965+
[`git_strarray`](http://libgit2.github.com/libgit2/#HEAD/type/git_strarray),
966+
[`git_index_add_all`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_add_all),
967+
[`git_index_remove_all`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_remove_all),
968+
[`git_index_update_all`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_update_all)
969+
)
970+
971+
972+
800973
<h2 id="status">Status</h2>
801974
802975
<h3 id="status_iterating_simple">Iterating (Simple)</h3>

0 commit comments

Comments
 (0)