Skip to content

Commit abfb539

Browse files
benben
committed
Index content
1 parent 0f4ee87 commit abfb539

File tree

1 file changed

+119
-16
lines changed

1 file changed

+119
-16
lines changed

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

Lines changed: 119 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -802,85 +802,188 @@ int error = git_tag_peel(&dereferenced_target, tag);
802802
<h3 id="index_loading">Loading</h3>
803803

804804
```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");
805811
```
806812

807813
(
808-
[``](),
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)
809816
)
810817

811-
<h3 id="index_creating">Creating</h3>
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.
812821

813822
```c
823+
git_index *idx = NULL;
824+
int error = git_index_new(&idx);
814825
```
815826

816827
(
817-
[``](),
828+
[`git_index_new`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_new)
818829
)
819830

820831
<h3 id="index_capabilities">Capabilities</h3>
821832

833+
An index has certain properties, indicated by capability flags.
834+
822835
```c
836+
unsigned int caps = git_index_caps(idx);
837+
838+
/* These are settable as well */
839+
caps |= GIT_INDEXCAP_NO_SYMLINKS;
840+
int error = git_index_set_caps(idx, caps);
823841
```
824842

825843
(
826-
[``](),
844+
[`git_index_caps`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_caps),
845+
[`git_indexcap_t`](http://libgit2.github.com/libgit2/#HEAD/type/git_indexcap_t)
827846
)
828847

829848
<h3 id="index_disk">Disk</h3>
830849

831850
```c
851+
/* Make the in-memory index match what's on disk */
852+
int error = git_index_read(idx, true);
853+
854+
/* Write the in-memory index to disk */
855+
error = git_index_write(idx);
832856
```
833857

834858
(
835-
[``](),
859+
[`git_index_read`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_read),
860+
[`git_index_write`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_write)
836861
)
837862

838863
<h3 id="index_trees">Trees</h3>
839864

840865
```c
866+
/* Overwrite the index contents with those of a tree */
867+
git_tree *tree = NULL;
868+
int error = git_revparse_single((git_object**)&tree,
869+
repo, "HEAD~^{tree}");
870+
error = git_index_read_tree(idx, tree);
871+
872+
/* Write the index contents to the ODB as a tree */
873+
git_oid new_tree_id = {{0}};
874+
error = git_index_write_tree(&new_tree_id, idx);
875+
876+
/* In-memory indexes can write trees to any repo */
877+
error = git_index_write_tree_to(&new_tree_id, idx, other_repo);
841878
```
842879
843880
(
844-
[``](),
881+
[`git_revparse_single`](http://libgit2.github.com/libgit2/#HEAD/group/revparse/git_revparse_single),
882+
[`git_index_read_tree`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_read_tree),
883+
[`git_index_write_tree`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_write_tree),
884+
[`git_index_write_tree_to`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_write_tree_to)
845885
)
846886
847887
<h3 id="index_entries">Entries</h3>
848888
849889
```c
890+
/* Access by index */
891+
size_t count = git_index_entrycount(idx);
892+
for (size_t i=0; i<count; i++) {
893+
const git_index_entry *entry = git_index_get_byindex(idx, i);
894+
/* … */
895+
}
896+
897+
/* Access by path */
898+
const git_index_entry *entry = git_index_get_bypath(
899+
idx, /* index */
900+
"path/to/file.rb", /* path */
901+
0); /* stage */
850902
```
851903

852904
(
853-
[``](),
905+
[`git_index_entrycount`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_entrycount),
906+
[`git_index_get_byindex`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_get_byindex),
907+
[`git_index_get_bypath`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_get_bypath),
908+
[`git_index_entry`](http://libgit2.github.com/libgit2/#HEAD/type/git_index_entry)
854909
)
855910

856911
<h3 id="index_conflicts">Conflicts</h3>
857912

858913
```c
914+
if (git_index_has_conflicts(idx)) {
915+
/* If you know the path of a conflicted file */
916+
const git_index_entry *ancestor = NULL,
917+
*ours = NULL,
918+
*theirs = NULL;
919+
int error = git_index_conflict_get(&ancestor, &ours, &theirs
920+
idx, "path/to/file.cs");
921+
922+
/* Or, iterate through all conflicts */
923+
git_index_conflict_iterator *iter = NULL;
924+
error = git_index_conflict_iterator_new(&iter, idx);
925+
while (git_index_conflict_next(&ancestor, &ours, &theirs, iter)
926+
!= GIT_ITEROVER) {
927+
/* Mark this conflict as resolved */
928+
error = git_index_conflict_remove(idx, ours->path);
929+
}
930+
git_index_conflict_iterator_free(iter);
931+
}
859932
```
860933

861934
(
862-
[``](),
935+
[`git_index_has_conflicts`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_has_conflicts),
936+
[`git_index_conflict_get`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_get),
937+
[`git_index_conflict_iterator_new`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_iterator_new),
938+
[`git_index_conflict_next`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_next),
939+
[`git_index_conflict_iterator_free`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_iterator_free),
940+
[`git_index_conflict_remove`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_conflict_remove)
863941
)
864942

865-
<h3 id="index_add">Add</h3>
943+
<h3 id="index_add">Add & Remove</h3>
866944

867945
```c
868-
```
946+
typedef struct { /* … */ } match_data;
947+
int match_cb(const char *path, const char *spec, void *payload)
948+
{
949+
match_data *d = (match_data*)payload;
950+
/*
951+
* return 0 to add/remove this path,
952+
* a positive number to skip this path,
953+
* or a negative number to abort the operation.
954+
*/
955+
}
869956

870-
(
871-
[``](),
872-
)
957+
const char *paths[] = {"src/*", "test/*"};
958+
git_strarray arr = {paths, 2};
873959

874-
<h3 id="index_remove">Remove</h3>
960+
/* Add matching files; this skips ignored files */
961+
match_data d = {0};
962+
int error = git_index_add_all(idx, &arr, GIT_INDEX_ADD_DEFAULT,
963+
match_cb, &d);
964+
/* … or remove them */
965+
error = git_index_remove_all(idx, &arr, match_cb, &d);
875966

876-
```c
967+
/* Something like 'git add .' */
968+
error = git_index_update_all(idx, &arr, match_cb, &d);
969+
970+
/* Force a single file to be added (even if it is ignored) */
971+
error = git_index_add_bypath(idx, "path/to/file.py");
972+
/* …or removed */
973+
error = git_index_remove_bypath(idx, "path/to/file.py");
877974
```
878975
879976
(
880-
[``](),
977+
[`git_strarray`](http://libgit2.github.com/libgit2/#HEAD/type/git_strarray),
978+
[`git_index_add_all`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_add_all),
979+
[`git_index_remove_all`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_remove_all),
980+
[`git_index_update_all`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_update_all),
981+
[`git_index_add_bypath`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_add_bypath),
982+
[`git_index_remove_bypath`](http://libgit2.github.com/libgit2/#HEAD/group/index/git_index_remove_bypath)
881983
)
882984
883985
986+
884987
<h2 id="status">Status</h2>
885988
886989
<h3 id="status_iterating_simple">Iterating (Simple)</h3>

0 commit comments

Comments
 (0)