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_git_blob_h__ 8 #define INCLUDE_git_blob_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 #include "object.h" 14 #include "buffer.h" 15 16 /** 17 * @file git2/blob.h 18 * @brief Git blob load and write routines 19 * @defgroup git_blob Git blob load and write routines 20 * @ingroup Git 21 * @{ 22 */ 23 GIT_BEGIN_DECL 24 25 /** 26 * Lookup a blob object from a repository. 27 * 28 * @param blob pointer to the looked up blob 29 * @param repo the repo to use when locating the blob. 30 * @param id identity of the blob to locate. 31 * @return 0 or an error code 32 */ 33 GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id); 34 35 /** 36 * Lookup a blob object from a repository, 37 * given a prefix of its identifier (short id). 38 * 39 * @see git_object_lookup_prefix 40 * 41 * @param blob pointer to the looked up blob 42 * @param repo the repo to use when locating the blob. 43 * @param id identity of the blob to locate. 44 * @param len the length of the short identifier 45 * @return 0 or an error code 46 */ 47 GIT_EXTERN(int) git_blob_lookup_prefix(git_blob **blob, git_repository *repo, const git_oid *id, size_t len); 48 49 /** 50 * Close an open blob 51 * 52 * This is a wrapper around git_object_free() 53 * 54 * IMPORTANT: 55 * It *is* necessary to call this method when you stop 56 * using a blob. Failure to do so will cause a memory leak. 57 * 58 * @param blob the blob to close 59 */ 60 GIT_EXTERN(void) git_blob_free(git_blob *blob); 61 62 /** 63 * Get the id of a blob. 64 * 65 * @param blob a previously loaded blob. 66 * @return SHA1 hash for this blob. 67 */ 68 GIT_EXTERN(const git_oid *) git_blob_id(const git_blob *blob); 69 70 /** 71 * Get the repository that contains the blob. 72 * 73 * @param blob A previously loaded blob. 74 * @return Repository that contains this blob. 75 */ 76 GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob); 77 78 /** 79 * Get a read-only buffer with the raw content of a blob. 80 * 81 * A pointer to the raw content of a blob is returned; 82 * this pointer is owned internally by the object and shall 83 * not be free'd. The pointer may be invalidated at a later 84 * time. 85 * 86 * @param blob pointer to the blob 87 * @return the pointer 88 */ 89 GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob); 90 91 /** 92 * Get the size in bytes of the contents of a blob 93 * 94 * @param blob pointer to the blob 95 * @return size on bytes 96 */ 97 GIT_EXTERN(git_object_size_t) git_blob_rawsize(const git_blob *blob); 98 99 /** 100 * Flags to control the functionality of `git_blob_filter`. 101 */ 102 typedef enum { 103 /** When set, filters will not be applied to binary files. */ 104 GIT_BLOB_FILTER_CHECK_FOR_BINARY = (1 << 0), 105 106 /** 107 * When set, filters will not load configuration from the 108 * system-wide `gitattributes` in `/etc` (or system equivalent). 109 */ 110 GIT_BLOB_FILTER_NO_SYSTEM_ATTRIBUTES = (1 << 1), 111 112 /** 113 * When set, filters will be loaded from a `.gitattributes` file 114 * in the HEAD commit. 115 */ 116 GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD = (1 << 2), 117 } git_blob_filter_flag_t; 118 119 /** 120 * The options used when applying filter options to a file. 121 */ 122 typedef struct { 123 int version; 124 125 /** Flags to control the filtering process, see `git_blob_filter_flag_t` above */ 126 uint32_t flags; 127 } git_blob_filter_options; 128 129 #define GIT_BLOB_FILTER_OPTIONS_VERSION 1 130 #define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY} 131 132 /** 133 * Get a buffer with the filtered content of a blob. 134 * 135 * This applies filters as if the blob was being checked out to the 136 * working directory under the specified filename. This may apply 137 * CRLF filtering or other types of changes depending on the file 138 * attributes set for the blob and the content detected in it. 139 * 140 * The output is written into a `git_buf` which the caller must free 141 * when done (via `git_buf_dispose`). 142 * 143 * If no filters need to be applied, then the `out` buffer will just 144 * be populated with a pointer to the raw content of the blob. In 145 * that case, be careful to *not* free the blob until done with the 146 * buffer or copy it into memory you own. 147 * 148 * @param out The git_buf to be filled in 149 * @param blob Pointer to the blob 150 * @param as_path Path used for file attribute lookups, etc. 151 * @param opts Options to use for filtering the blob 152 * @return 0 on success or an error code 153 */ 154 GIT_EXTERN(int) git_blob_filter( 155 git_buf *out, 156 git_blob *blob, 157 const char *as_path, 158 git_blob_filter_options *opts); 159 160 /** 161 * Read a file from the working folder of a repository 162 * and write it to the Object Database as a loose blob 163 * 164 * @param id return the id of the written blob 165 * @param repo repository where the blob will be written. 166 * this repository cannot be bare 167 * @param relative_path file from which the blob will be created, 168 * relative to the repository's working dir 169 * @return 0 or an error code 170 */ 171 GIT_EXTERN(int) git_blob_create_from_workdir(git_oid *id, git_repository *repo, const char *relative_path); 172 173 /** 174 * Read a file from the filesystem and write its content 175 * to the Object Database as a loose blob 176 * 177 * @param id return the id of the written blob 178 * @param repo repository where the blob will be written. 179 * this repository can be bare or not 180 * @param path file from which the blob will be created 181 * @return 0 or an error code 182 */ 183 GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, const char *path); 184 185 /** 186 * Create a stream to write a new blob into the object db 187 * 188 * This function may need to buffer the data on disk and will in 189 * general not be the right choice if you know the size of the data 190 * to write. If you have data in memory, use 191 * `git_blob_create_from_buffer()`. If you do not, but know the size of 192 * the contents (and don't want/need to perform filtering), use 193 * `git_odb_open_wstream()`. 194 * 195 * Don't close this stream yourself but pass it to 196 * `git_blob_create_from_stream_commit()` to commit the write to the 197 * object db and get the object id. 198 * 199 * If the `hintpath` parameter is filled, it will be used to determine 200 * what git filters should be applied to the object before it is written 201 * to the object database. 202 * 203 * @param out the stream into which to write 204 * @param repo Repository where the blob will be written. 205 * This repository can be bare or not. 206 * @param hintpath If not NULL, will be used to select data filters 207 * to apply onto the content of the blob to be created. 208 * @return 0 or error code 209 */ 210 GIT_EXTERN(int) git_blob_create_from_stream( 211 git_writestream **out, 212 git_repository *repo, 213 const char *hintpath); 214 215 /** 216 * Close the stream and write the blob to the object db 217 * 218 * The stream will be closed and freed. 219 * 220 * @param out the id of the new blob 221 * @param stream the stream to close 222 * @return 0 or an error code 223 */ 224 GIT_EXTERN(int) git_blob_create_from_stream_commit( 225 git_oid *out, 226 git_writestream *stream); 227 228 /** 229 * Write an in-memory buffer to the ODB as a blob 230 * 231 * @param id return the id of the written blob 232 * @param repo repository where to blob will be written 233 * @param buffer data to be written into the blob 234 * @param len length of the data 235 * @return 0 or an error code 236 */ 237 GIT_EXTERN(int) git_blob_create_from_buffer( 238 git_oid *id, git_repository *repo, const void *buffer, size_t len); 239 240 /** 241 * Determine if the blob content is most certainly binary or not. 242 * 243 * The heuristic used to guess if a file is binary is taken from core git: 244 * Searching for NUL bytes and looking for a reasonable ratio of printable 245 * to non-printable characters among the first 8000 bytes. 246 * 247 * @param blob The blob which content should be analyzed 248 * @return 1 if the content of the blob is detected 249 * as binary; 0 otherwise. 250 */ 251 GIT_EXTERN(int) git_blob_is_binary(const git_blob *blob); 252 253 /** 254 * Create an in-memory copy of a blob. The copy must be explicitly 255 * free'd or it will leak. 256 * 257 * @param out Pointer to store the copy of the object 258 * @param source Original object to copy 259 */ 260 GIT_EXTERN(int) git_blob_dup(git_blob **out, git_blob *source); 261 262 /** @} */ 263 GIT_END_DECL 264 #endif 265
