[libgit2.git] / include / git2 / attr.h

/*
 * Copyright (C) 2009-2012 the libgit2 contributors
 *
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
 */
#ifndef INCLUDE_git_attr_h__
#define INCLUDE_git_attr_h__

#include "common.h"
#include "types.h"

/**
 * @file git2/attr.h
 * @brief Git attribute management routines
 * @defgroup git_attr Git attribute management routines
 * @ingroup Git
 * @{
 */
GIT_BEGIN_DECL

/**
 * GIT_ATTR_TRUE checks if an attribute is set on.  In core git
 * parlance, this the value for "Set" attributes.
 *
 * For example, if the attribute file contains:
 *
 *    *.c foo
 *
 * Then for file `xyz.c` looking up attribute "foo" gives a value for
 * which `GIT_ATTR_TRUE(value)` is true.
 */
#define GIT_ATTR_TRUE(attr)	(git_attr_value(attr) == GIT_ATTR_TRUE_T)

/**
 * GIT_ATTR_FALSE checks if an attribute is set off.  In core git
 * parlance, this is the value for attributes that are "Unset" (not to
 * be confused with values that a "Unspecified").
 *
 * For example, if the attribute file contains:
 *
 *    *.h -foo
 *
 * Then for file `zyx.h` looking up attribute "foo" gives a value for
 * which `GIT_ATTR_FALSE(value)` is true.
 */
#define GIT_ATTR_FALSE(attr) (git_attr_value(attr) == GIT_ATTR_FALSE_T)

/**
 * GIT_ATTR_UNSPECIFIED checks if an attribute is unspecified.  This
 * may be due to the attribute not being mentioned at all or because
 * the attribute was explicitly set unspecified via the `!` operator.
 *
 * For example, if the attribute file contains:
 *
 *    *.c foo
 *    *.h -foo
 *    onefile.c !foo
 *
 * Then for `onefile.c` looking up attribute "foo" yields a value with
 * `GIT_ATTR_UNSPECIFIED(value)` of true.  Also, looking up "foo" on
 * file `onefile.rb` or looking up "bar" on any file will all give
 * `GIT_ATTR_UNSPECIFIED(value)` of true.
 */
#define GIT_ATTR_UNSPECIFIED(attr) (git_attr_value(attr) == GIT_ATTR_UNSPECIFIED_T)

/**
 * GIT_ATTR_HAS_VALUE checks if an attribute is set to a value (as
 * opposed to TRUE, FALSE or UNSPECIFIED).  This would be the case if
 * for a file with something like:
 *
 *    *.txt eol=lf
 *
 * Given this, looking up "eol" for `onefile.txt` will give back the
 * string "lf" and `GIT_ATTR_SET_TO_VALUE(attr)` will return true.
 */
#define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_T)

typedef enum {
	GIT_ATTR_UNSPECIFIED_T = 0,
	GIT_ATTR_TRUE_T,
	GIT_ATTR_FALSE_T,
	GIT_ATTR_VALUE_T,
} git_attr_t;

/*
 *	Return the value type for a given attribute.
 *
 *	This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute
 *	was not set at all), or `VALUE`, if the attribute was set to
 *	an actual string.
 *
 *	If the attribute has a `VALUE` string, it can be accessed normally
 *	as a NULL-terminated C string.
 *
 *	@param attr The attribute
 *	@return the value type for the attribute
 */
GIT_EXTERN(git_attr_t) git_attr_value(const char *attr);

/**
 * Check attribute flags: Reading values from index and working directory.
 *
 * When checking attributes, it is possible to check attribute files
 * in both the working directory (if there is one) and the index (if
 * there is one).  You can explicitly choose where to check and in
 * which order using the following flags.
 *
 * Core git usually checks the working directory then the index,
 * except during a checkout when it checks the index first.  It will
 * use index only for creating archives or for a bare repo (if an
 * index has been specified for the bare repo).
 */
#define GIT_ATTR_CHECK_FILE_THEN_INDEX	0
#define GIT_ATTR_CHECK_INDEX_THEN_FILE	1
#define GIT_ATTR_CHECK_INDEX_ONLY		2

/**
 * Check attribute flags: Using the system attributes file.
 *
 * Normally, attribute checks include looking in the /etc (or system
 * equivalent) directory for a `gitattributes` file.  Passing this
 * flag will cause attribute checks to ignore that file.
 */
#define GIT_ATTR_CHECK_NO_SYSTEM		(1 << 2)

/**
 * Look up the value of one git attribute for path.
 *
 * @param value_out Output of the value of the attribute.  Use the GIT_ATTR_...
 *             macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just
 *             use the string value for attributes set to a value.  You
 *             should NOT modify or free this value.
 * @param repo The repository containing the path.
 * @param flags A combination of GIT_ATTR_CHECK... flags.
 * @param path The path to check for attributes.  Relative paths are
 *             interpreted relative to the repo root.  The file does
 *             not have to exist, but if it does not, then it will be
 *             treated as a plain file (not a directory).
 * @param name The name of the attribute to look up.
 */
GIT_EXTERN(int) git_attr_get(
	const char **value_out,
    git_repository *repo,
	uint32_t flags,
	const char *path,
	const char *name);

/**
 * Look up a list of git attributes for path.
 *
 * Use this if you have a known list of attributes that you want to
 * look up in a single call.  This is somewhat more efficient than
 * calling `git_attr_get()` multiple times.
 *
 * For example, you might write:
 *
 *     const char *attrs[] = { "crlf", "diff", "foo" };
 *     const char **values[3];
 *     git_attr_get_many(values, repo, 0, "my/fun/file.c", 3, attrs);
 *
 * Then you could loop through the 3 values to get the settings for
 * the three attributes you asked about.
 *
 * @param values An array of num_attr entries that will have string
 *             pointers written into it for the values of the attributes.
 *             You should not modify or free the values that are written
 *             into this array (although of course, you should free the
 *             array itself if you allocated it).
 * @param repo The repository containing the path.
 * @param flags A combination of GIT_ATTR_CHECK... flags.
 * @param path The path inside the repo to check attributes.  This
 *             does not have to exist, but if it does not, then
 *             it will be treated as a plain file (i.e. not a directory).
 * @param num_attr The number of attributes being looked up
 * @param names An array of num_attr strings containing attribute names.
 */
GIT_EXTERN(int) git_attr_get_many(
	const char **values_out,
	git_repository *repo,
	uint32_t flags,
	const char *path,
	size_t num_attr,
	const char **names);

/**
 * Loop over all the git attributes for a path.
 *
 * @param repo The repository containing the path.
 * @param flags A combination of GIT_ATTR_CHECK... flags.
 * @param path Path inside the repo to check attributes.  This does not have
 *             to exist, but if it does not, then it will be treated as a
 *             plain file (i.e. not a directory).
 * @param callback Function to invoke on each attribute name and value.  The
 *             value may be NULL is the attribute is explicitly set to
 *             UNSPECIFIED using the '!' sign.  Callback will be invoked
 *             only once per attribute name, even if there are multiple
 *             rules for a given file.  The highest priority rule will be
 *             used.  Return a non-zero value from this to stop looping.
 * @param payload Passed on as extra parameter to callback function.
 * @return 0 on success, GIT_EUSER on non-zero callback, or error code
 */
GIT_EXTERN(int) git_attr_foreach(
	git_repository *repo,
	uint32_t flags,
	const char *path,
	int (*callback)(const char *name, const char *value, void *payload),
	void *payload);

/**
 * Flush the gitattributes cache.
 *
 * Call this if you have reason to believe that the attributes files on
 * disk no longer match the cached contents of memory.  This will cause
 * the attributes files to be reloaded the next time that an attribute
 * access function is called.
 */
GIT_EXTERN(void) git_attr_cache_flush(
	git_repository *repo);

/**
 * Add a macro definition.
 *
 * Macros will automatically be loaded from the top level `.gitattributes`
 * file of the repository (plus the build-in "binary" macro).  This
 * function allows you to add others.  For example, to add the default
 * macro, you would call:
 *
 *    git_attr_add_macro(repo, "binary", "-diff -crlf");
 */
GIT_EXTERN(int) git_attr_add_macro(
	git_repository *repo,
	const char *name,
	const char *values);

/** @} */
GIT_END_DECL
#endif
Commit	Line	Data
ee1f0b1a	1	/*
5e0de328	2	* Copyright (C) 2009-2012 the libgit2 contributors
ee1f0b1a RB	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_attr_h__
	8	#define INCLUDE_git_attr_h__
	9
	10	#include "common.h"
	11	#include "types.h"
	12
	13	/**
	14	* @file git2/attr.h
	15	* @brief Git attribute management routines
	16	* @defgroup git_attr Git attribute management routines
	17	* @ingroup Git
	18	* @{
	19	*/
	20	GIT_BEGIN_DECL
	21
f917481e RB	22	/**
	23	* GIT_ATTR_TRUE checks if an attribute is set on. In core git
	24	* parlance, this the value for "Set" attributes.
	25	*
	26	* For example, if the attribute file contains:
	27	*
	28	* *.c foo
	29	*
	30	* Then for file `xyz.c` looking up attribute "foo" gives a value for
	31	* which `GIT_ATTR_TRUE(value)` is true.
	32	*/
0c9eacf3	33	#define GIT_ATTR_TRUE(attr) (git_attr_value(attr) == GIT_ATTR_TRUE_T)
f917481e RB	34
	35	/**
	36	* GIT_ATTR_FALSE checks if an attribute is set off. In core git
	37	* parlance, this is the value for attributes that are "Unset" (not to
	38	* be confused with values that a "Unspecified").
	39	*
	40	* For example, if the attribute file contains:
	41	*
	42	* *.h -foo
	43	*
	44	* Then for file `zyx.h` looking up attribute "foo" gives a value for
	45	* which `GIT_ATTR_FALSE(value)` is true.
	46	*/
0c9eacf3	47	#define GIT_ATTR_FALSE(attr) (git_attr_value(attr) == GIT_ATTR_FALSE_T)
f917481e RB	48
	49	/**
	50	* GIT_ATTR_UNSPECIFIED checks if an attribute is unspecified. This
	51	* may be due to the attribute not being mentioned at all or because
	52	* the attribute was explicitly set unspecified via the `!` operator.
	53	*
	54	* For example, if the attribute file contains:
	55	*
	56	* *.c foo
	57	* *.h -foo
	58	* onefile.c !foo
	59	*
	60	* Then for `onefile.c` looking up attribute "foo" yields a value with
	61	* `GIT_ATTR_UNSPECIFIED(value)` of true. Also, looking up "foo" on
	62	* file `onefile.rb` or looking up "bar" on any file will all give
	63	* `GIT_ATTR_UNSPECIFIED(value)` of true.
	64	*/
0c9eacf3	65	#define GIT_ATTR_UNSPECIFIED(attr) (git_attr_value(attr) == GIT_ATTR_UNSPECIFIED_T)
f917481e RB	66
f917481e RB	67	/**
29e948de	68	* GIT_ATTR_HAS_VALUE checks if an attribute is set to a value (as
d73c94b2	69	* opposed to TRUE, FALSE or UNSPECIFIED). This would be the case if
f917481e RB	70	* for a file with something like:
	71	*
	72	* *.txt eol=lf
	73	*
	74	* Given this, looking up "eol" for `onefile.txt` will give back the
	75	* string "lf" and `GIT_ATTR_SET_TO_VALUE(attr)` will return true.
	76	*/
0c9eacf3	77	#define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_T)
ee1f0b1a	78
0c9eacf3 VM	79	typedef enum {
	80	GIT_ATTR_UNSPECIFIED_T = 0,
	81	GIT_ATTR_TRUE_T,
	82	GIT_ATTR_FALSE_T,
	83	GIT_ATTR_VALUE_T,
	84	} git_attr_t;
	85
	86	/*
	87	* Return the value type for a given attribute.
	88	*
	89	* This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute
	90	* was not set at all), or `VALUE`, if the attribute was set to
	91	* an actual string.
	92	*
	93	* If the attribute has a `VALUE` string, it can be accessed normally
	94	* as a NULL-terminated C string.
	95	*
	96	* @param attr The attribute
	97	* @return the value type for the attribute
	98	*/
5389005d	99	GIT_EXTERN(git_attr_t) git_attr_value(const char *attr);
ee1f0b1a	100
f917481e RB	101	/**
	102	* Check attribute flags: Reading values from index and working directory.
	103	*
	104	* When checking attributes, it is possible to check attribute files
	105	* in both the working directory (if there is one) and the index (if
	106	* there is one). You can explicitly choose where to check and in
	107	* which order using the following flags.
	108	*
	109	* Core git usually checks the working directory then the index,
	110	* except during a checkout when it checks the index first. It will
	111	* use index only for creating archives or for a bare repo (if an
	112	* index has been specified for the bare repo).
	113	*/
	114	#define GIT_ATTR_CHECK_FILE_THEN_INDEX 0
	115	#define GIT_ATTR_CHECK_INDEX_THEN_FILE 1
	116	#define GIT_ATTR_CHECK_INDEX_ONLY 2
ee1f0b1a RB	117
ee1f0b1a RB	118	/**
f917481e RB	119	* Check attribute flags: Using the system attributes file.
	120	*
	121	* Normally, attribute checks include looking in the /etc (or system
	122	* equivalent) directory for a `gitattributes` file. Passing this
	123	* flag will cause attribute checks to ignore that file.
	124	*/
	125	#define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2)
	126
	127	/**
	128	* Look up the value of one git attribute for path.
	129	*
29e948de VM	130	* @param value_out Output of the value of the attribute. Use the GIT_ATTR_...
	131	* macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just
	132	* use the string value for attributes set to a value. You
	133	* should NOT modify or free this value.
f917481e RB	134	* @param repo The repository containing the path.
	135	* @param flags A combination of GIT_ATTR_CHECK... flags.
	136	* @param path The path to check for attributes. Relative paths are
	137	* interpreted relative to the repo root. The file does
	138	* not have to exist, but if it does not, then it will be
	139	* treated as a plain file (not a directory).
	140	* @param name The name of the attribute to look up.
ee1f0b1a RB	141	*/
ee1f0b1a RB	142	GIT_EXTERN(int) git_attr_get(
29e948de	143	const char **value_out,
f917481e RB	144	git_repository *repo,
	145	uint32_t flags,
	146	const char *path,
29e948de	147	const char *name);
ee1f0b1a RB	148
ee1f0b1a RB	149	/**
f917481e RB	150	* Look up a list of git attributes for path.
	151	*
	152	* Use this if you have a known list of attributes that you want to
	153	* look up in a single call. This is somewhat more efficient than
	154	* calling `git_attr_get()` multiple times.
	155	*
	156	* For example, you might write:
	157	*
	158	* const char *attrs[] = { "crlf", "diff", "foo" };
	159	* const char **values[3];
29e948de	160	* git_attr_get_many(values, repo, 0, "my/fun/file.c", 3, attrs);
f917481e RB	161	*
	162	* Then you could loop through the 3 values to get the settings for
	163	* the three attributes you asked about.
	164	*
29e948de VM	165	* @param values An array of num_attr entries that will have string
	166	* pointers written into it for the values of the attributes.
	167	* You should not modify or free the values that are written
	168	* into this array (although of course, you should free the
	169	* array itself if you allocated it).
f917481e RB	170	* @param repo The repository containing the path.
	171	* @param flags A combination of GIT_ATTR_CHECK... flags.
	172	* @param path The path inside the repo to check attributes. This
	173	* does not have to exist, but if it does not, then
	174	* it will be treated as a plain file (i.e. not a directory).
	175	* @param num_attr The number of attributes being looked up
	176	* @param names An array of num_attr strings containing attribute names.
ee1f0b1a RB	177	*/
ee1f0b1a RB	178	GIT_EXTERN(int) git_attr_get_many(
29e948de	179	const char **values_out,
b709e951	180	git_repository *repo,
f917481e RB	181	uint32_t flags,
f917481e RB	182	const char *path,
b709e951	183	size_t num_attr,
29e948de	184	const char **names);
ee1f0b1a RB	185
ee1f0b1a RB	186	/**
f917481e RB	187	* Loop over all the git attributes for a path.
	188	*
	189	* @param repo The repository containing the path.
	190	* @param flags A combination of GIT_ATTR_CHECK... flags.
5dca2010 RB	191	* @param path Path inside the repo to check attributes. This does not have
	192	* to exist, but if it does not, then it will be treated as a
	193	* plain file (i.e. not a directory).
	194	* @param callback Function to invoke on each attribute name and value. The
	195	* value may be NULL is the attribute is explicitly set to
	196	* UNSPECIFIED using the '!' sign. Callback will be invoked
	197	* only once per attribute name, even if there are multiple
	198	* rules for a given file. The highest priority rule will be
	199	* used. Return a non-zero value from this to stop looping.
f917481e	200	* @param payload Passed on as extra parameter to callback function.
5dca2010	201	* @return 0 on success, GIT_EUSER on non-zero callback, or error code
ee1f0b1a RB	202	*/
ee1f0b1a RB	203	GIT_EXTERN(int) git_attr_foreach(
b709e951	204	git_repository *repo,
f917481e RB	205	uint32_t flags,
f917481e RB	206	const char *path,
ee1f0b1a RB	207	int (callback)(const char name, const char value, void payload),
	208	void *payload);
	209
73b51450 RB	210	/**
	211	* Flush the gitattributes cache.
	212	*
f917481e RB	213	* Call this if you have reason to believe that the attributes files on
	214	* disk no longer match the cached contents of memory. This will cause
	215	* the attributes files to be reloaded the next time that an attribute
	216	* access function is called.
73b51450 RB	217	*/
	218	GIT_EXTERN(void) git_attr_cache_flush(
	219	git_repository *repo);
	220
	221	/**
	222	* Add a macro definition.
	223	*
f917481e	224	* Macros will automatically be loaded from the top level `.gitattributes`
73b51450 RB	225	* file of the repository (plus the build-in "binary" macro). This
	226	* function allows you to add others. For example, to add the default
	227	* macro, you would call:
	228	*
	229	* git_attr_add_macro(repo, "binary", "-diff -crlf");
	230	*/
	231	GIT_EXTERN(int) git_attr_add_macro(
	232	git_repository *repo,
	233	const char *name,
	234	const char *values);
	235
ee1f0b1a RB	236	/** @} */
	237	GIT_END_DECL
	238	#endif
	239