2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_git_common_h__
8 #define INCLUDE_git_common_h__
14 # define GIT_BEGIN_DECL extern "C" {
15 # define GIT_END_DECL }
17 /** Start declarations in C mode */
18 # define GIT_BEGIN_DECL /* empty */
19 /** End declarations in C mode */
20 # define GIT_END_DECL /* empty */
23 #if defined(_MSC_VER) && _MSC_VER < 1800
25 # include "inttypes.h"
27 /** This check is needed for importing this file in an iOS/OS X framework throws an error in Xcode otherwise.*/
28 #elif !defined(__CLANG_INTTYPES_H)
29 # include <inttypes.h>
34 * This is so clang's doc parser acknowledges comments on functions
35 * with size_t parameters.
37 typedef size_t size_t;
40 /** Declare a public function exported for application use. */
42 # define GIT_EXTERN(type) extern \
43 __attribute__((visibility("default"))) \
45 #elif defined(_MSC_VER)
46 # define GIT_EXTERN(type) __declspec(dllexport) type
48 # define GIT_EXTERN(type) extern type
51 /** Declare a function's takes printf style arguments. */
53 # define GIT_FORMAT_PRINTF(a,b) __attribute__((format (printf, a, b)))
55 # define GIT_FORMAT_PRINTF(a,b) /* empty */
58 #if (defined(_WIN32)) && !defined(__CYGWIN__)
63 #include <netinet/in.h>
68 * @brief Git common platform definitions
69 * @defgroup git_common Git common platform definitions
77 * The separator used in path list strings (ie like in the PATH
78 * environment variable). A semi-colon ";" is used on Windows, and
79 * a colon ":" for all other systems.
82 #define GIT_PATH_LIST_SEPARATOR ';'
84 #define GIT_PATH_LIST_SEPARATOR ':'
88 * The maximum length of a valid git path.
90 #define GIT_PATH_MAX 4096
93 * The string representation of the null object ID.
95 #define GIT_OID_HEX_ZERO "0000000000000000000000000000000000000000"
98 * Return the version of the libgit2 library
99 * being currently used.
101 * @param major Store the major version number
102 * @param minor Store the minor version number
103 * @param rev Store the revision (patch) number
105 GIT_EXTERN(void) git_libgit2_version(int *major
, int *minor
, int *rev
);
108 * Combinations of these values describe the features with which libgit2
113 * If set, libgit2 was built thread-aware and can be safely used from multiple
116 GIT_FEATURE_THREADS
= (1 << 0),
118 * If set, libgit2 was built with and linked against a TLS implementation.
119 * Custom TLS streams may still be added by the user to support HTTPS
120 * regardless of this.
122 GIT_FEATURE_HTTPS
= (1 << 1),
124 * If set, libgit2 was built with and linked against libssh2. A custom
125 * transport may still be added by the user to support libssh2 regardless of
128 GIT_FEATURE_SSH
= (1 << 2),
130 * If set, libgit2 was built with support for sub-second resolution in file
131 * modification times.
133 GIT_FEATURE_NSEC
= (1 << 3),
137 * Query compile time options for libgit2.
139 * @return A combination of GIT_FEATURE_* values.
141 * - GIT_FEATURE_THREADS
142 * Libgit2 was compiled with thread support. Note that thread support is
143 * still to be seen as a 'work in progress' - basic object lookups are
144 * believed to be threadsafe, but other operations may not be.
146 * - GIT_FEATURE_HTTPS
147 * Libgit2 supports the https:// protocol. This requires the openssl
148 * library to be found when compiling libgit2.
151 * Libgit2 supports the SSH protocol for network operations. This requires
152 * the libssh2 library to be found when compiling libgit2
154 GIT_EXTERN(int) git_libgit2_features(void);
157 * Global library options
159 * These are used to select which global option to set or get and are
160 * used in `git_libgit2_opts()`.
163 GIT_OPT_GET_MWINDOW_SIZE
,
164 GIT_OPT_SET_MWINDOW_SIZE
,
165 GIT_OPT_GET_MWINDOW_MAPPED_LIMIT
,
166 GIT_OPT_SET_MWINDOW_MAPPED_LIMIT
,
167 GIT_OPT_GET_SEARCH_PATH
,
168 GIT_OPT_SET_SEARCH_PATH
,
169 GIT_OPT_SET_CACHE_OBJECT_LIMIT
,
170 GIT_OPT_SET_CACHE_MAX_SIZE
,
171 GIT_OPT_ENABLE_CACHING
,
172 GIT_OPT_GET_CACHED_MEMORY
,
173 GIT_OPT_GET_TEMPLATE_PATH
,
174 GIT_OPT_SET_TEMPLATE_PATH
,
175 GIT_OPT_SET_SSL_CERT_LOCATIONS
,
176 GIT_OPT_SET_USER_AGENT
,
177 GIT_OPT_ENABLE_STRICT_OBJECT_CREATION
,
178 GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION
,
179 GIT_OPT_SET_SSL_CIPHERS
,
180 GIT_OPT_GET_USER_AGENT
,
181 GIT_OPT_ENABLE_OFS_DELTA
,
182 GIT_OPT_ENABLE_FSYNC_GITDIR
,
183 GIT_OPT_GET_WINDOWS_SHAREMODE
,
184 GIT_OPT_SET_WINDOWS_SHAREMODE
,
185 GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION
,
189 * Set or query a library global option
193 * * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *):
195 * > Get the maximum mmap window size
197 * * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t):
199 * > Set the maximum mmap window size
201 * * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *):
203 * > Get the maximum memory that will be mapped in total by the library
205 * * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t):
207 * >Set the maximum amount of memory that can be mapped at any time
210 * * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf)
212 * > Get the search path for a given level of config data. "level" must
213 * > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`,
214 * > `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`.
215 * > The search path is written to the `out` buffer.
217 * * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path)
219 * > Set the search path for a level of config data. The search path
220 * > applied to shared attributes and ignore files, too.
222 * > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR.
223 * > Pass NULL to reset to the default (generally based on environment
224 * > variables). Use magic path `$PATH` to include the old value
225 * > of the path (if you want to prepend or append, for instance).
227 * > - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`,
228 * > `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or
229 * > `GIT_CONFIG_LEVEL_PROGRAMDATA`.
231 * * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_otype type, size_t size)
233 * > Set the maximum data size for the given type of object to be
234 * > considered eligible for caching in memory. Setting to value to
235 * > zero means that that type of object will not be cached.
236 * > Defaults to 0 for GIT_OBJ_BLOB (i.e. won't cache blobs) and 4k
237 * > for GIT_OBJ_COMMIT, GIT_OBJ_TREE, and GIT_OBJ_TAG.
239 * * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes)
241 * > Set the maximum total data size that will be cached in memory
242 * > across all repositories before libgit2 starts evicting objects
243 * > from the cache. This is a soft limit, in that the library might
244 * > briefly exceed it, but will start aggressively evicting objects
245 * > from cache when that happens. The default cache size is 256MB.
247 * * opts(GIT_OPT_ENABLE_CACHING, int enabled)
249 * > Enable or disable caching completely.
251 * > Because caches are repository-specific, disabling the cache
252 * > cannot immediately clear all cached objects, but each cache will
253 * > be cleared on the next attempt to update anything in it.
255 * * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed)
257 * > Get the current bytes in cache and the maximum that would be
258 * > allowed in the cache.
260 * * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out)
262 * > Get the default template path.
263 * > The path is written to the `out` buffer.
265 * * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path)
267 * > Set the default template path.
269 * > - `path` directory of template.
271 * * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path)
273 * > Set the SSL certificate-authority locations.
275 * > - `file` is the location of a file containing several
276 * > certificates concatenated together.
277 * > - `path` is the location of a directory holding several
278 * > certificates, one per file.
280 * > Either parameter may be `NULL`, but not both.
282 * * opts(GIT_OPT_SET_USER_AGENT, const char *user_agent)
284 * > Set the value of the User-Agent header. This value will be
285 * > appended to "git/1.0", for compatibility with other git clients.
287 * > - `user_agent` is the value that will be delivered as the
288 * > User-Agent header on HTTP requests.
290 * * opts(GIT_OPT_SET_WINDOWS_SHAREMODE, unsigned long value)
292 * > Set the share mode used when opening files on Windows.
293 * > For more information, see the documentation for CreateFile.
294 * > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE. This is
295 * > ignored and unused on non-Windows platforms.
297 * * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value)
299 * > Get the share mode used when opening files on Windows.
301 * * opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled)
303 * > Enable strict input validation when creating new objects
304 * > to ensure that all inputs to the new objects are valid. For
305 * > example, when this is enabled, the parent(s) and tree inputs
306 * > will be validated when creating a new commit. This defaults
309 * * opts(GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled)
311 * > Validate the target of a symbolic ref when creating it. For
312 * > example, `foobar` is not a valid ref, therefore `foobar` is
313 * > not a valid target for a symbolic ref by default, whereas
314 * > `refs/heads/foobar` is. Disabling this bypasses validation
315 * > so that an arbitrary strings such as `foobar` can be used
316 * > for a symbolic ref target. This defaults to enabled.
318 * * opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers)
320 * > Set the SSL ciphers use for HTTPS connections.
322 * > - `ciphers` is the list of ciphers that are eanbled.
324 * * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled)
326 * > Enable or disable the use of "offset deltas" when creating packfiles,
327 * > and the negotiation of them when talking to a remote server.
328 * > Offset deltas store a delta base location as an offset into the
329 * > packfile from the current location, which provides a shorter encoding
330 * > and thus smaller resultant packfiles.
331 * > Packfiles containing offset deltas can still be read.
332 * > This defaults to enabled.
334 * * opts(GIT_OPT_ENABLE_FSYNC_GITDIR, int enabled)
336 * > Enable synchronized writes of files in the gitdir using `fsync`
337 * > (or the platform equivalent) to ensure that new object data
338 * > is written to permanent storage, not simply cached. This
339 * > defaults to disabled.
341 * opts(GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, int enabled)
343 * > Enable strict verification of object hashsums when reading
344 * > objects from disk. This may impact performance due to an
345 * > additional checksum calculation on each object. This defaults
348 * @param option Option key
349 * @param ... value to set the option
350 * @return 0 on success, <0 on failure
352 GIT_EXTERN(int) git_libgit2_opts(int option
, ...);