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, or NULL on error 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_ATTRIBUTES_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 * Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can 123 * use `git_blob_filter_options_init`. 124 * 125 */ 126 typedef struct { 127 int version; 128 129 /** Flags to control the filtering process, see `git_blob_filter_flag_t` above */ 130 uint32_t flags; 131 } git_blob_filter_options; 132 133 #define GIT_BLOB_FILTER_OPTIONS_VERSION 1 134 #define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY} 135 136 /** 137 * Initialize git_blob_filter_options structure 138 * 139 * Initializes a `git_blob_filter_options` with default values. Equivalent 140 * to creating an instance with `GIT_BLOB_FILTER_OPTIONS_INIT`. 141 * 142 * @param opts The `git_blob_filter_options` struct to initialize. 143 * @param version The struct version; pass `GIT_BLOB_FILTER_OPTIONS_VERSION`. 144 * @return Zero on success; -1 on failure. 145 */ 146 GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsigned int version); 147 148 /** 149 * Get a buffer with the filtered content of a blob. 150 * 151 * This applies filters as if the blob was being checked out to the 152 * working directory under the specified filename. This may apply 153 * CRLF filtering or other types of changes depending on the file 154 * attributes set for the blob and the content detected in it. 155 * 156 * The output is written into a `git_buf` which the caller must free 157 * when done (via `git_buf_dispose`). 158 * 159 * If no filters need to be applied, then the `out` buffer will just 160 * be populated with a pointer to the raw content of the blob. In 161 * that case, be careful to *not* free the blob until done with the 162 * buffer or copy it into memory you own. 163 * 164 * @param out The git_buf to be filled in 165 * @param blob Pointer to the blob 166 * @param as_path Path used for file attribute lookups, etc. 167 * @param opts Options to use for filtering the blob 168 * @return 0 on success or an error code 169 */ 170 GIT_EXTERN(int) git_blob_filter( 171 git_buf *out, 172 git_blob *blob, 173 const char *as_path, 174 git_blob_filter_options *opts); 175 176 /** 177 * Read a file from the working folder of a repository 178 * and write it to the Object Database as a loose blob 179 * 180 * @param id return the id of the written blob 181 * @param repo repository where the blob will be written. 182 * this repository cannot be bare 183 * @param relative_path file from which the blob will be created, 184 * relative to the repository's working dir 185 * @return 0 or an error code 186 */ 187 GIT_EXTERN(int) git_blob_create_from_workdir(git_oid *id, git_repository *repo, const char *relative_path); 188 189 /** 190 * Read a file from the filesystem and write its content 191 * to the Object Database as a loose blob 192 * 193 * @param id return the id of the written blob 194 * @param repo repository where the blob will be written. 195 * this repository can be bare or not 196 * @param path file from which the blob will be created 197 * @return 0 or an error code 198 */ 199 GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, const char *path); 200 201 /** 202 * Create a stream to write a new blob into the object db 203 * 204 * This function may need to buffer the data on disk and will in 205 * general not be the right choice if you know the size of the data 206 * to write. If you have data in memory, use 207 * `git_blob_create_from_buffer()`. If you do not, but know the size of 208 * the contents (and don't want/need to perform filtering), use 209 * `git_odb_open_wstream()`. 210 * 211 * Don't close this stream yourself but pass it to 212 * `git_blob_create_from_stream_commit()` to commit the write to the 213 * object db and get the object id. 214 * 215 * If the `hintpath` parameter is filled, it will be used to determine 216 * what git filters should be applied to the object before it is written 217 * to the object database. 218 * 219 * @param out the stream into which to write 220 * @param repo Repository where the blob will be written. 221 * This repository can be bare or not. 222 * @param hintpath If not NULL, will be used to select data filters 223 * to apply onto the content of the blob to be created. 224 * @return 0 or error code 225 */ 226 GIT_EXTERN(int) git_blob_create_from_stream( 227 git_writestream **out, 228 git_repository *repo, 229 const char *hintpath); 230 231 /** 232 * Close the stream and write the blob to the object db 233 * 234 * The stream will be closed and freed. 235 * 236 * @param out the id of the new blob 237 * @param stream the stream to close 238 * @return 0 or an error code 239 */ 240 GIT_EXTERN(int) git_blob_create_from_stream_commit( 241 git_oid *out, 242 git_writestream *stream); 243 244 /** 245 * Write an in-memory buffer to the ODB as a blob 246 * 247 * @param id return the id of the written blob 248 * @param repo repository where to blob will be written 249 * @param buffer data to be written into the blob 250 * @param len length of the data 251 * @return 0 or an error code 252 */ 253 GIT_EXTERN(int) git_blob_create_from_buffer( 254 git_oid *id, git_repository *repo, const void *buffer, size_t len); 255 256 /** 257 * Determine if the blob content is most certainly binary or not. 258 * 259 * The heuristic used to guess if a file is binary is taken from core git: 260 * Searching for NUL bytes and looking for a reasonable ratio of printable 261 * to non-printable characters among the first 8000 bytes. 262 * 263 * @param blob The blob which content should be analyzed 264 * @return 1 if the content of the blob is detected 265 * as binary; 0 otherwise. 266 */ 267 GIT_EXTERN(int) git_blob_is_binary(const git_blob *blob); 268 269 /** 270 * Create an in-memory copy of a blob. The copy must be explicitly 271 * free'd or it will leak. 272 * 273 * @param out Pointer to store the copy of the object 274 * @param source Original object to copy 275 */ 276 GIT_EXTERN(int) git_blob_dup(git_blob **out, git_blob *source); 277 278 /** @} */ 279 GIT_END_DECL 280 #endif 281