summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorrsiddharth <rsiddharth@ninthfloor.org>2013-10-19 21:29:05 +0530
committerrsiddharth <rsiddharth@ninthfloor.org>2013-10-19 21:31:35 +0530
commit6bc0ecb31345d377fb507aa8e488269060d5bc1c (patch)
treea0997f30c765ecc124008f3f6ea7513fe673ceda
parentcf7022a6b3dcfa60049fdc515733401b0d6c57bb (diff)
added READMEv0.1
It contains info about gitblag, documentation on how to setup and start using the script.
-rw-r--r--README109
-rw-r--r--how-it-works.txt102
-rw-r--r--sample-commit-msg.txt38
3 files changed, 249 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..bd57efc
--- /dev/null
+++ b/README
@@ -0,0 +1,109 @@
+<!-- -*- mode: markdown; -*- -->
+
+# gitblag
+
+`gitblag` is a simple hook script to automatically send an email to an
+mailing list whenever a new entry/essay/post is pushed to a
+website/blog maintained using [git][git], the stupid content tracker.
+
+The subject and the body of the email is slurped from the commit
+message.
+
+`gitblag` is based on the `post-receive-email` script found in the
+contrib/hooks directory in the [Git SCM][git]'s source.
+
+[git]: http://git-scm.com/
+
+See 'Using gitblag' for info on how to install and use it.
+
+## Etymology
+
+The name `gitblag` resulted from copulative compounding of two
+obvious word stems -- `git` & `blag`.
+
+The word `blag`, a mispronunciation of `blog`, AFAIK, (first) appeared
+in the [xkcd comic][blag].
+
+[blag]: http://xkcd.com/148/
+
+## License
+
+`gitblag` is licensed under the GNU General Public License version 3
+or later. See COPYING for the full text of the license.
+
+## Using gitblag
+
+`gitblag` is meant to be used as a post-receive hook on a bare remote
+git repository of a website/blog. This hook is invoked on the remote
+repository when a `git push` happens on the local repository.
+
+The `gitblag` script does two things:
+
++ Sends an email to a mailing list when it finds a specifically
+ formatted `commit` (See 'Commit Message Format' section), on the
+ *master* branch.
+
++ Checks out the latest version of the working tree.
+
+For help setting up a website/blog maintained using git, read [Using
+Git to manage a web site][git-website].
+
+[git-website]: http://toroid.org/ams/git-website-howto
+
+### Installation
+
+Get a copy.
+
+ $ git clone http://rsiddharth.ninth.su/git/gitblag.git
+
+Copy the script to the bare git repo of the website/blog.
+
+ $ cd /path/to/your/bare/repo/wobsite.git
+
+ $ cp /path/to/gitblag/gitblag.sh hooks/post-receive
+
+ $ chmod 755 hooks/post-receive
+
+Specify the location of the git maintained website/blog by changing
+the value of `GIT_WORK_TREE` variable in the `hooks/post-receive`
+script.
+
+### Configuration
+
+Go to the bare git repo of the website/blog.
+
+ $ cd /path/to/your/bare/repo/wobsite.git
+
+Set up the mailing list to which the script should send emails to.
+
+ $ git config --local --add hooks.mailinglist yourblag@list.tld
+
+Set up the email prefix. All emails will have their subjects prefixed
+with this prefix, "[Mailing List Prefix]" if emailprefix is not set.
+
+ $ git config --local --add hooks.emailprefix "[ BLAG PREFIX ]"
+
+Set up the mailing list footer. Edit the `description` file in the
+bare git repo.
+
+ $ editor description
+
+To set a custom `From` field, the hooks.envelopesender option needs to
+be set.
+
+ $ git config --local --add hooks.envelopesender from@address.tld
+
+### Commit Message Format
+
++ Start the commit message with `[NEW POST]` followed by text that
+will be used as the subject of the email.
+
++ Leave a blank line.
+
++ Write the body of the email.
+
+See the `sample-commit-msg.txt` file.
+
+## Contact
+
+ rsiddharth `<rsiddharth@ninthfloor.org>`
diff --git a/how-it-works.txt b/how-it-works.txt
new file mode 100644
index 0000000..a603544
--- /dev/null
+++ b/how-it-works.txt
@@ -0,0 +1,102 @@
+tree fdc6f9d5db67e89713850cc323798a04c2d5a344
+parent f406c4e9e3708f9a08e90db0d3e44651d3a247c8
+author rsiddharth <rsiddharth@ninthfloor.org> 1381308376 +0530
+committer rsiddharth <rsiddharth@ninthfloor.org> 1381308376 +0530
+
+[NEW POST] Foo Bar Post Subject goes here.
+
+Body of the post goes here. Lorem ipsum dolor sit amet, consectetur
+adipiscing elit. Donec a diam lectus. Sed sit amet ipsum
+mauris. Maecenas congue ligula ac quam viverra nec consectetur ante
+hendrerit. Donec et mollis dolor. Praesent et diam eget libero egestas
+mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem
+lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non
+tortor. Lorem ipsum dolor sit amet, consectetur adipiscing
+elit. Aenean ut gravida lorem. Ut turpis felis, pulvinar a semper sed,
+adipiscing id dolor. Pellentesque auctor nisi id magna consequat
+sagittis. Curabitur dapibus enim sit amet elit pharetra tincidunt
+feugiat nisl imperdiet. Ut convallis libero in urna ultrices
+accumsan. Donec sed odio eros. Donec viverra mi quis quam pulvinar at
+malesuada arcu rhoncus. Cum sociis natoque penatibus et magnis dis
+parturient montes, nascetur ridiculus mus. In rutrum accumsan
+ultricies. Mauris vitae nisi at sem [facilisis][1] semper ac in est.
+
+[1]: http://some.link.com
+
+Vivamus fermentum semper porta. Nunc diam velit, adipiscing ut
+tristique vitae, sagittis vel odio. Maecenas convallis ullamcorper
+ultricies. Curabitur ornare, ligula semper consectetur sagittis, nisi
+diam iaculis velit, id fringilla sem nunc vel mi. Nam dictum, odio nec
+pretium volutpat, arcu ante placerat erat, non tristique elit urna et
+turpis. Quisque mi metus, ornare sit amet fermentum et, tincidunt et
+orci. Fusce eget orci a [orci][2] congue vestibulum. Ut dolor diam,
+elementum et vestibulum eu, porttitor vel elit. Curabitur venenatis
+pulvinar tellus gravida ornare. Sed et erat faucibus nunc euismod
+ultricies ut id justo. Nullam cursus suscipit nisi, et ultrices justo
+sodales nec. Fusce venenatis facilisis lectus ac semper. Aliquam at
+massa ipsum. Quisque bibendum purus convallis nulla ultrices
+ultricies. Nullam aliquam, mi eu [aliquam tincidunt][3], purus velit
+laoreet tortor, viverra pretium nisi quam vitae mi. Fusce vel volutpat
+elit. Nam sagittis nisi dui.
+
+[2]: http://another.link.com
+[3]: http://yet.another.link.com
+
+ | |
+ | | The above commit object is converted
+ | | to an email message like the one
+ | | below, by the gitblag script.
+ \| |/ ______________________________________
+ \ / | |
+ \/ | Note that on most email-clients |
+ | X-Git-* , Auto-Submitted fields are |
+ | not shown. |
+ |______________________________________|
+
+
+To: rsiddharth@ninthfloor.org
+Subject: Foo Bar Post Subject goes here.
+X-Git-Refname: refs/heads/master
+X-Git-Reftype: branch
+X-Git-Oldrev: f406c4e9e3708f9a08e90db0d3e44651d3a247c8
+X-Git-Newrev: 942cb638e27a659b16449970941a8111dd34db0c
+Auto-Submitted: auto-generated
+Date: Wed, 9 Oct 2013 08:46:59 +0000 (UTC)
+From: rsiddharth@ninthfloor.org
+
+Body of the post goes here. Lorem ipsum dolor sit amet, consectetur
+adipiscing elit. Donec a diam lectus. Sed sit amet ipsum
+mauris. Maecenas congue ligula ac quam viverra nec consectetur ante
+hendrerit. Donec et mollis dolor. Praesent et diam eget libero egestas
+mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem
+lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non
+tortor. Lorem ipsum dolor sit amet, consectetur adipiscing
+elit. Aenean ut gravida lorem. Ut turpis felis, pulvinar a semper sed,
+adipiscing id dolor. Pellentesque auctor nisi id magna consequat
+sagittis. Curabitur dapibus enim sit amet elit pharetra tincidunt
+feugiat nisl imperdiet. Ut convallis libero in urna ultrices
+accumsan. Donec sed odio eros. Donec viverra mi quis quam pulvinar at
+malesuada arcu rhoncus. Cum sociis natoque penatibus et magnis dis
+parturient montes, nascetur ridiculus mus. In rutrum accumsan
+ultricies. Mauris vitae nisi at sem [facilisis][1] semper ac in est.
+
+[1]: http://some.link.com
+
+Vivamus fermentum semper porta. Nunc diam velit, adipiscing ut
+tristique vitae, sagittis vel odio. Maecenas convallis ullamcorper
+ultricies. Curabitur ornare, ligula semper consectetur sagittis, nisi
+diam iaculis velit, id fringilla sem nunc vel mi. Nam dictum, odio nec
+pretium volutpat, arcu ante placerat erat, non tristique elit urna et
+turpis. Quisque mi metus, ornare sit amet fermentum et, tincidunt et
+orci. Fusce eget orci a [orci][2] congue vestibulum. Ut dolor diam,
+elementum et vestibulum eu, porttitor vel elit. Curabitur venenatis
+pulvinar tellus gravida ornare. Sed et erat faucibus nunc euismod
+ultricies ut id justo. Nullam cursus suscipit nisi, et ultrices justo
+sodales nec. Fusce venenatis facilisis lectus ac semper. Aliquam at
+massa ipsum. Quisque bibendum purus convallis nulla ultrices
+ultricies. Nullam aliquam, mi eu [aliquam tincidunt][3], purus velit
+laoreet tortor, viverra pretium nisi quam vitae mi. Fusce vel volutpat
+elit. Nam sagittis nisi dui.
+
+[2]: http://another.link.com
+[3]: http://yet.another.link.com
diff --git a/sample-commit-msg.txt b/sample-commit-msg.txt
new file mode 100644
index 0000000..f73ede0
--- /dev/null
+++ b/sample-commit-msg.txt
@@ -0,0 +1,38 @@
+[NEW POST] Foo Bar Post Subject goes here.
+
+Body of the post goes here. Lorem ipsum dolor sit amet, consectetur
+adipiscing elit. Donec a diam lectus. Sed sit amet ipsum
+mauris. Maecenas congue ligula ac quam viverra nec consectetur ante
+hendrerit. Donec et mollis dolor. Praesent et diam eget libero egestas
+mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem
+lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non
+tortor. Lorem ipsum dolor sit amet, consectetur adipiscing
+elit. Aenean ut gravida lorem. Ut turpis felis, pulvinar a semper sed,
+adipiscing id dolor. Pellentesque auctor nisi id magna consequat
+sagittis. Curabitur dapibus enim sit amet elit pharetra tincidunt
+feugiat nisl imperdiet. Ut convallis libero in urna ultrices
+accumsan. Donec sed odio eros. Donec viverra mi quis quam pulvinar at
+malesuada arcu rhoncus. Cum sociis natoque penatibus et magnis dis
+parturient montes, nascetur ridiculus mus. In rutrum accumsan
+ultricies. Mauris vitae nisi at sem [facilisis][1] semper ac in est.
+
+[1]: http://some.link.com
+
+Vivamus fermentum semper porta. Nunc diam velit, adipiscing ut
+tristique vitae, sagittis vel odio. Maecenas convallis ullamcorper
+ultricies. Curabitur ornare, ligula semper consectetur sagittis, nisi
+diam iaculis velit, id fringilla sem nunc vel mi. Nam dictum, odio nec
+pretium volutpat, arcu ante placerat erat, non tristique elit urna et
+turpis. Quisque mi metus, ornare sit amet fermentum et, tincidunt et
+orci. Fusce eget orci a [orci][2] congue vestibulum. Ut dolor diam,
+elementum et vestibulum eu, porttitor vel elit. Curabitur venenatis
+pulvinar tellus gravida ornare. Sed et erat faucibus nunc euismod
+ultricies ut id justo. Nullam cursus suscipit nisi, et ultrices justo
+sodales nec. Fusce venenatis facilisis lectus ac semper. Aliquam at
+massa ipsum. Quisque bibendum purus convallis nulla ultrices
+ultricies. Nullam aliquam, mi eu [aliquam tincidunt][3], purus velit
+laoreet tortor, viverra pretium nisi quam vitae mi. Fusce vel volutpat
+elit. Nam sagittis nisi dui.
+
+[2]: http://another.link.com
+[3]: http://yet.another.link.com