src/reader.h

   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