Re: [PATCH] Quick description of possible gitattributes system

[Junio C Hamano <junkio@cox.net>]

Andy Parkins <andyparkins@gmail.com> writes:

> +Attributes are attached to paths in one of two ways:
> +
> + - Via the .gitattributes file.  This will work in the same way as the
> +   .gitignore file.  That is, there can be multiple .gitattributes files
> +   throughout the working directory.
> +
> +   Typically the .gitattributes file will be a version controlled file,
> +   just like .gitignore.

Another point to stress here is that these are property of the
paths of the project and independent of the platform each user
happens to have a repository of the project on.  If something is
text, then it is text whether the platform is on UNIX or on DOS.

> +   It will obviously be of different format from the .gitattributes
> +   file, but the attribute names and path specification will be
> +   identical (and specified as if from the root of the repository tree).

I am in favor of also using $GIT_DIR/config format even for the
in-tree .gitattributes files.  For one thing, it makes the
syntax and quoting rules saner and more consistent (blanks in
pathname patterns and such), and we already have a parser for
it.

	[attribute "image/png"]
        	path = "*.png"

	[attribute "image/jpg"]
        	path = "*.jpg"
        	path = "*.jpeg"

	[attribute "text"]
		; anything that is image/* is non-text -- I am
                ; not sure if we want to allow this which means
                ; we need to resolve dependencies, though.
                attr = "!image/*"
		; inside list of path-patterns, the first match wins.
		path = "!this-is-not-text.txt"
        	path = "*"

	; .gitignore is a mere special case of "ignored" attribute.
	[attribute "ignored"]
        	path = "*~"
                path = "!hand-maintained.o"
                path = "*.[aso]"

Earlier, I said attributes are property of project, but that
does not mean we should forbid users to define more paths in
config.  On DOS, you might want to have:

	[attribute "ignored"]
        	path = "*.obj"

to suppliment the last entry of the above "ignored" that is
meant to catch object files, until the upstream project adds it
to the .gitattribute files.

In contrast to that attributes define property of paths of the
project, handlers define how we should behave on paths with
certain attributes in a particular repository.  So it is
important to stress that that handler sections should never
appear in in-tree .gitattributes files.  Because they are
per-repository, the same project checked out on DOS will be used
with this handler definition (which would be the built-in
default not to require the users to have one in ~/.gitconfig):

	[handler "text"]
        	input = crlf
                output = crlf

while on UNIX the input/output would be no-op.

> +----------------------------------------
> +[handler "fix-line-endings"]
> +  attribute = text/plain
> +  infilter = eol_lf
> +  outfilter = eol_local
> +----------------------------------------
> +
> +This definition creates a handler named "fix-line-endings" (don't suppose
> +they actually need names) that would run the "eol_lf" filter on check
> +in, and the "eol_local" filter on checkout.

I would suggest making handler section _match_ the attribute
names.  By "match", what I mean is to allow something like this:

	[handler "image/*"]
        	pretty = "cmd display -"

even though the attributes are "image/png", "image/jpg", etc.

> +[handler "show-images"]
> +  attribute = image/gif
> +  prettyfilter = pipe display -

I would recommend against calling them *filter.  After all, the
semantics of each handler action (such as input, output and
pretty) already determine if it needs to act as a filter or data
sink.  We do not need to say prettyfilter either; it is not even
a filter to begin with -- it is a data sink.