README.md in git-meta-1.0.0 vs README.md in git-meta-2.0.0

- old
+ new

@@ -9,36 +9,48 @@ It is also completely compatible for people wanting to read this metadata directly from an interface like git-log or github. Syntax ------ -In your git commit, you just need a section that looks something like the following: +In your git commit, you just need a few yaml-like structures like the following: - ---git-meta--- - foo: - bar: "baz" - ---git-meta--- + foo: bar + Signed-Off-By: Me! -This is a YAML formatted block. Currently the only way of setting this metadata is writing the YAML by hand in the commit message. +Currently the only way of setting this metadata is writing the YAML by hand in the commit message. The Regex that i use (no longer a YAML parser for simplification) will catch all non-whitespace before each colon and the rest of the line afterwards. +The change where I have removed YAML means that we can no longer have hierarchal data structures, which both makes it easier to use with small amounts of data but harder to use with larger amounts of data. + +If you want to re-implement this in another language, I ask that you please use the following regular expression to parse the git messages (we make a call to the `git-cat-file` utility to get the messages): + + /(\S+):\s*(.+)$/ + Usage ===== -Querying --------- +Getting +------- -You can use `git-meta [sha|ref] --get-all` to return just the YAML-block. +You can use `git-meta get [ sha | ref ]` to return all keys and values. `[ sha | ref ]` can be anything that `git-cat-file` will understand. -You can also use `git-meta [sha|ref] --get foo.bar` to return "baz" from the earlier example. Will return an empty string if nothing is returned for that piece of metadata. +You can also use `git-meta get [ sha | ref ] --get foo` to return "bar" from the earlier example. Will return an empty string if nothing is returned for that piece of metadata. -If you were to specify just `--get foo` then the underlying YAML would be returned (in this case `bar: "baz"`). +I am aware that this is open to shenanigans including something like `git-meta get 'HEAD && echo "foo: baz"'` but really, I don't care. I don't foresee this being used anywhere that would be a problem - ie i guess it will mostly be used by a person wanting the data, or a computer processing the data with other values like commit shas or refs that it has deduced itself. -Storing +Setting ------- -I have not yet got this sorted. I need to think a bit more about this. +I have not yet got this sorted. A solution will be forthcoming in a compatible release, but at the moment i have not yet thought enough about how it's going to be implemented. -I originally thought i could use `./.git/COMMIT\_EDIT\_MSG` but it turns out that is overwritten just before every commit. Whack me an email or a github message if you want to help with this feature, or have an idea for implementation. +Installation +============ + +As easy as `gem install git-meta` (as long as you have gemcutter as a source) + +Requirements +============ + +Only `shoulda` and `mocra` for testing. I have tried to keep this as lean as possible. Copyright --------- Copyright (c) 2009 Sam Elliott. See LICENSE for details. (MIT Licence)