matchexpression: New plumbing command to check if a preferred content expression matches some data.

doc/bugs/treatment_of_largefiles_is_not_working_for_addurl_--fast___40__or_--relaxed__41__/comment_4_00dfd040f4d8b9f1ed765ee38dbc67b9._comment

@@ -0,0 +1,16 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 4"""
+ date="2016-01-25T20:15:05Z"
+ content="""
+Implemented the matchexpression command.
+
+	time for x in $(seq 1 100); do git annex matchexpression "include=*.png and largerthan=100mb" --file=foo.png --size=10mb --debug; done
+	
+	real	0m5.167s
+	user	0m2.688s
+	sys	0m1.860s
+
+Don't know if that's fast enough or if it will need further optimisation
+or a --batch option..
+"""]]

doc/git-annex-matchexpression.mdwn

@@ -0,0 +1,51 @@
+# NAME
+
+git-annex matchexpression - checks if a preferred content expression matches
+
+# SYNOPSIS
+
+git annex matchexpression `expression [data]`
+
+# DESCRIPTION
+
+This plumbing-level command is given a prefferred content expression,
+and some data, and checks if the expression matches the data. It exits 0 if
+it matches, and 1 if not. If not enough data was provided, it displays an
+error and exits with special code 42.
+
+For example, this will exit 0:
+
+	git annex matchexpression "include=*.png and largerthan=1mb" --file=foo.png --size=10mb
+
+# OPTIONS
+
+* `--file=`
+
+  Provide the filename to match against. Note that the file does not have
+  to actually exist on disk.
+
+* `--size=`
+
+  Tell what the size of the file is. The size can be specified with any
+  commonly used units, for example, "0.5 gb" or "100 KiloBytes".
+
+* `--key=`
+
+  Tell what key is being matched against. This is needed for
+  matching expressions like "copies=N" and "metadata=tag=foo" and
+  "present", which all need to look up the information on file for a key.
+
+  Many keys have a known size, and so --size is not needed when specifying
+  such a key.
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-preferred-content]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.

doc/git-annex.mdwn

@@ -535,6 +535,12 @@ subdirectories).
   
   See [[git-annex-examinekey]](1) for details.
 
+* `matchexpression`
+
+  Checks if a preferred content expression matches provided data.
+  
+  See [[git-annex-matchexpression]](1) for details.
+
 * `fromkey [key file]`
 
   Manually set up a file in the git repository to link to a specified key.
@@ -553,7 +559,6 @@ subdirectories).
   
   See [[git-annex-setkey]](1) for details.
 
-
 * `dropkey [key ...]`
 
   Drops annexed content for specified keys.