1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 #ifndef INCLUDE_reader_h__ 8 #define INCLUDE_reader_h__ 9 10 #include "common.h" 11 12 /* Returned when the workdir does not match the index */ 13 #define GIT_READER_MISMATCH 1 14 15 typedef struct git_reader git_reader; 16 17 /* 18 * The `git_reader` structure is a generic interface for reading the 19 * contents of a file by its name, and implementations are provided 20 * for reading out of a tree, the index, and the working directory. 21 * 22 * Note that the reader implementation is meant to have a short 23 * lifecycle and does not increase the refcount of the object that 24 * it's reading. Callers should ensure that they do not use a 25 * reader after disposing the underlying object that it reads. 26 */ 27 struct git_reader { 28 int (*read)(git_buf *out, git_oid *out_oid, git_filemode_t *mode, git_reader *reader, const char *filename); 29 }; 30 31 /** 32 * Create a `git_reader` that will allow random access to the given 33 * tree. Paths requested via `git_reader_read` will be rooted at this 34 * tree, callers are not expected to recurse through tree lookups. Thus, 35 * you can request to read `/src/foo.c` and the tree provided to this 36 * function will be searched to find another tree named `src`, which 37 * will then be opened to find `foo.c`. 38 * 39 * @param out The reader for the given tree 40 * @param tree The tree object to read 41 * @return 0 on success, or an error code < 0 42 */ 43 extern int git_reader_for_tree( 44 git_reader **out, 45 git_tree *tree); 46 47 /** 48 * Create a `git_reader` that will allow random access to the given 49 * index, or the repository's index. 50 * 51 * @param out The reader for the given index 52 * @param repo The repository containing the index 53 * @param index The index to read, or NULL to use the repository's index 54 * @return 0 on success, or an error code < 0 55 */ 56 extern int git_reader_for_index( 57 git_reader **out, 58 git_repository *repo, 59 git_index *index); 60 61 /** 62 * Create a `git_reader` that will allow random access to the given 63 * repository's working directory. Note that the contents are read 64 * in repository format, meaning any workdir -> odb filters are 65 * applied. 66 * 67 * If `validate_index` is set to true, reads of files will hash the 68 * on-disk contents and ensure that the resulting object ID matches 69 * the repository's index. This ensures that the working directory 70 * is unmodified from the index contents. 71 * 72 * @param out The reader for the given working directory 73 * @param repo The repository containing the working directory 74 * @param validate_index If true, the working directory contents will 75 * be compared to the index contents during read to ensure that 76 * the working directory is unmodified. 77 * @return 0 on success, or an error code < 0 78 */ 79 extern int git_reader_for_workdir( 80 git_reader **out, 81 git_repository *repo, 82 bool validate_index); 83 84 /** 85 * Read the given filename from the reader and populate the given buffer 86 * with the contents and the given oid with the object ID. 87 * 88 * @param out The buffer to populate with the file contents 89 * @param out_id The oid to populate with the object ID 90 * @param reader The reader to read 91 * @param filename The filename to read from the reader 92 */ 93 extern int git_reader_read( 94 git_buf *out, 95 git_oid *out_id, 96 git_filemode_t *out_filemode, 97 git_reader *reader, 98 const char *filename); 99 100 /** 101 * Free the given reader and any associated objects. 102 * 103 * @param reader The reader to free 104 */ 105 extern void git_reader_free(git_reader *reader); 106 107 #endif 108