git-ged 0.0.2

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2011, John Sumsion
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the author nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/LICENSE.grit

@@ -0,0 +1,26 @@
+NOTE: Much of the structure of this rubygem, including the README was copied
+shamelessly from the grit gem, which seemed to be a very good example.
+Including this license here is an attempt to give proper attribution.
+
+(The MIT License)
+
+Copyright (c) 2007-2009 Tom Preston-Werner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+git-ged
+=======
+
+* Status: experimental
+* Author: John Sumsion
+* Inspiration: Git, Tim Shadel
+
+GEDCOM plugin for Git.  As a `git` subcommand, git-ged lets you import and
+manage GEDCOM files in a versioned, shareable way in a Git repository.
+
+It is also possible to attach to other repositories and fetch related
+genealogy from others who have imported it into their own repository.
+
+As a library, git-ged lets you write programs that communicate genealogical
+data in the git-ged repository layout.
+
+As a repository implementation, git-ged also defines a repository
+specification that, if adhered to by alternate implementations will render
+all implementations data-compatible with each other.
+
+The genealogical data format for persons and relationships is yet to be
+decided.  The first cut will be one that is largely one-to-one compatible
+with GEDCOM 5.5.  I fully expect to change the format before this
+solidifies, and I'll use whatever is the commonly-accepted format.
+
+
+## Requirements
+
+* git (http://git-scm.com) tested with 1.7.8
+* grit gem (https://github.com/mojombo/grit) tested with 2.4.1
+
+
+## Install
+
+Easiest install is via RubyGems:
+
+    $ gem install git-ged
+
+
+## Source
+
+Git-ged's Git repo is available on GitHub, which can be browsed at:
+
+    https://github.com/jsumsiong/git-ged
+
+and cloned with:
+
+    git clone https://github.com/jsumsiong/git-ged.git
+
+
+### Development
+
+You will need these gems to get tests to pass:
+
+* mocha
+
+
+### Contributing
+
+If you'd like to hack on git-ged, follow these instructions. To get all of the
+dependencies, install the gem first.
+
+1. Fork the project to your own account
+1. Clone down your fork
+1. Create a thoughtfully named topic branch to contain your change
+1. Hack away
+1. Add tests and make sure everything still passes by running `rake`
+1. If you are adding new functionality, document it in README.md
+1. Do not change the version number, I will do that on my end
+1. If necessary, rebase your commits into logical chunks, without errors
+1. Push the branch up to GitHub
+1. Send a pull request for your branch
+
+
+## Usage
+
+TODO
+
+Copyright
+---------
+
+Copyright (c) 2011 John Sumsion. See LICENSE for details.
+
+Portions Copyright (c) 2010 Tom Preston-Warner. See LICENSE.grit for details.  Thanks to the github folks for the inspiring Grit gem.

data/Rakefile

@@ -0,0 +1,149 @@
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test' << '.'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc "Generate RCov test coverage and open in your browser"
+task :coverage do
+  require 'rcov'
+  sh "rm -fr coverage"
+  sh "rcov test/test_*.rb"
+  sh "open coverage/index.html"
+end
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "#{name} #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+desc "Upload site to Rubyforge"
+task :site do
+  sh "scp -r doc/* jdsumsion@git-ged.rubyforge.org:/var/www/gforge-projects/git-ged"
+end
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg|test|experiments)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/TODO

@@ -0,0 +1,42 @@
+Structure
+- repo layout
+- library
+- commands
+
+Bootstrapping
+- integrate OptionParser (stdlib) and subcommand (gem) into git-ged commands
+- patch gem-man to read README{,.md} in lieu of any explicit manpage (gem man rib)
+
+- create licenses subdir with data licenses by short-name
+- create templates area that refs/heads/master can be populated from during "git ged init"
+- create git-ged command that invokes git-ged-*
+- create lib/git-ged/init.rb that invokes git init + template population (normal or bare)
+- create lib/git-ged/ingest.rb that copies a GEDCOM in and assigns permaname (refs/local/gedcoms)
+- ingest one of Hannah's small GEDCOMs
+- ingest one of Hannah's full GEDCOMs
+- get rib-git-ged plugin working
+
+- create living filter pipe for filtering GEDCOMs
+- create lib/git-ged/import.rb that copies a GEDCOM from refs/{local=>heads}/gedcoms with living filter
+- create person/family permaname generation strategies (_UUID or name/birth/death, parent permanames)
+- create entity permaname+state link logic
+- create lib/git-ged/import-person.rb that copies refs/heads/{gedcoms=>persons} (with living filter)
+- create lib/git-ged/import-family.rb that copies refs/heads/{gedcoms=>families} (with living filter)
+- import one of Hannah's GEDCOMs
+
+- populate person/family => gedcom permaname+state links
+- create ingest logic for dealing with the second ingest/import cycle on the same GEDCOM
+  - pick default person/family permaname generation logic based on whether the _UUIDs match up
+  - create local/gedcoms history based on 
+
+
+GUI:
+  shoes
+EXE:
+  ocra
+  shoes (for GUIs)
+Tools:
+  differ (ruby) for string diffs, edit distance style
+  datadiff (perl) annotated diff
+  datadiff (python) patch production
+

data/bin/git-ged

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'git-ged'
+GitGed::CLI.new.run

data/git-ged.gemspec

@@ -0,0 +1,51 @@
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.3.5'
+
+  $:.unshift(File.dirname(__FILE__))
+  require 'lib/git-ged'
+
+  s.name              = 'git-ged'
+  s.version           = GitGed::VERSION
+  s.date              = '2012-01-05'
+  #s.rubyforge_project = 'git-ged'
+
+  s.summary     = "GEDCOM plugin for Git"
+  s.description = "git-ged is a Ruby toolset for managing genealogical data (GEDCOM) inside a Git repository."
+
+  s.authors  = ["John Sumsion"]
+  s.email    = 'jdsumsion@gmail.com'
+  s.homepage = 'http://github.com/jdsumsion/git-ged'
+
+  s.require_paths = %w[lib]
+
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.extra_rdoc_files = %w[README.md LICENSE LICENSE.grit TODO layout.txt]
+
+  s.add_dependency('grit', "~> 2.4.1")
+  s.add_dependency('subcommand', "~> 1.0.6")
+
+  s.add_development_dependency('mocha')
+
+  s.executables << 'git-ged'
+
+  # = MANIFEST =
+  s.files = %w[
+    LICENSE
+    LICENSE.grit
+    README.md
+    Rakefile
+    TODO
+    bin/git-ged
+    git-ged.gemspec
+    layout.txt
+    lib/git-ged.rb
+    lib/git-ged/cli.rb
+    lib/git-ged/init.rb
+    lib/git-ged/repo.rb
+  ]
+  # = MANIFEST =
+
+  s.test_files = s.files.select { |path| path =~ /^test\/test_.*\.rb/ }
+end

data/layout.txt

@@ -0,0 +1,205 @@
+GIT-GED CONCEPTS
+================
+
+1) Git-ged commands
+[repo-level]
+- Init: populates refs/heads/{master,content,intent} with README, LICENSE_DEFAULT, etc. as specified by user
+- Clone: same as git clone
+- Attach: same as git remote add, except that it allows the user to define the set of permanames of interest in the remote repo
+- Fetch: same as git fetch, except that only permanames that the user currently has are fetched (along with refs/heads/master)
+- Push: same as git push, except that only permanames that the remote repo has are updated
+[entity-state]
+- Intent: captures one-line user intent (separate from commit message)
+- Ingest: populates refs/local/gedcoms/{permaname(s)} with a raw gedcom, adding new gedN files for permaname collisions
+- Filter: performs living filter and populates refs/heads/gedcoms/{permaname}
+- Import: creates any new persons/families and records import flag & new person/family permaname+state links in gedX.IMPORT
+[interactive-use]
+- Workspace: (subcommands: checkout, update, reset)
+  - checkout: grabs every specified person/family/gedcom permaname and puts it under the path repo/[persons|families|gedcoms]/{permaname} in a transient commit
+  - update: grabs the head of every specified person/family/gedcom permaname and puts it under a new refs/heads/workspace commit
+  - reset: warns if un-git-ged-committed refs/heads/workspace history, then nukes it and recreates a refs/heads/workspace commit with the same permanames as it had before
+- Resolve: deals with multiple-record histories in a smart way (gedcoms/persons/families)
+- Commit: creates commits on every separate permaname that has changed, using current intent as default commit subject plus details of all entities that changed
+
+2) Data Licenses
+- Data license defaults to Creative Commons Attribution-ShareAlike 3.0 Unported
+- Users can update license at repo/gedcom/record level
+- Other common license options are easily specifiable
+  - Other Creative Commons options: CC-BY-3.0, CC-BY-NC-3.0, CC-BY-NC-SA-3.0, CC0-1.0
+  - Open Data Commons options: ODC-PDDL-1.0, ODC-BY-1.0, ODC-ODBL-1.0
+
+3) Gedcom
+- all ingested gedcoms are stored verbatim under a "refs/local/gedcoms/{permaname}" ref
+- all imported, living-filtered gedcoms are stored under a "refs/heads/gedcoms/{permaname}" ref
+- there are multiple permanames for a gedcom:
+  - primary permaname for gedcom is the sha256 hash of "FILE & SUBM name[/email]"
+  - alternate permaname for gedcom is the sha256 hash of "FILE & DATE"
+  - alternate permaname for gedcom is the sha256 hash of "source path & SUBM name"
+  - alternate permaname for gedcom is the sha256 hash of all person _UUIDs, sorted alphanumerically
+- keep your email, paths & filenames consistent to maximize permaname collisions
+- copies the repo's LICENSE_DEFAULT unless overridden by the user at ingest time
+
+4) Person
+- all imported persons are stored in a standard JSON format under a "refs/heads/persons/{permaname}" refs
+- there are multiple permanames for a person:
+  - one is designated as primary, all permanames are annotated internally to the person by a versioned hash function (for easy recomputation)
+  - primary permaname for person defaults to the sha256 hash of the gedcom UID + sorted 'not-same-as' list
+  - alternate permaname for person is the sha256 hash of "<displayname>[ birthdate][ deathdate][ sorted 'not-same-as' list]" (can be designated as primary)
+  - alternate permaname for person is the sha256 hash of "<displayname> child of <permaname>" (for each parent, if there is no birth/death)
+  - other alternate permanames are definable, as long as the context-free code for computing them is included under refs/heads/code
+  - permanames based on "displayname" state should not change when the person's name is updated, they are designed to produce collisions based on import data
+  - although a person's primary permaname should remain largely constant, it can change for reasons of disambiguation (addition of a 'not-same-as' link)
+- proper protection of living data
+  - all imported persons must be deceased and publicly-viewable, or the record will initially exist under the "refs/local/persons/..." refspace
+  - import is responsible for initially segmenting living vs. deceased, but after import the app is responsible for calculating living after edit and moving the record if necessary
+  - the same living check & segmentation logic that import uses will be available on-demand for apps to use after edit
+  - when a deceased record is made living, the deceased record's permaname gets a new commit that marks it as no-longer-visible (so that on subsequent fetch, other repositories can delete their records)
+- includes optional "supersedes", "superseded-by", "derived-from", "same-as", and "not-same-as" link attributes
+  - see 
+  - the "derived-from", "supersedes", and "superseded-by" link attributes allow for proper history-aware
+    linkage across permanames for tracing merge or other complicated person record derivation
+  - the "same-as" attribute is a loose identity link to an alternate history of a person
+    determined to be the same historical person, it is a hint that a merge or other record derivation may be useful in the future
+  - if the "not-same-as" attribute refers to a disconnected history of a *different* person under the same permaname,
+    it is best to change the permaname of each person this attribute is added to
+- person merge is often not needed if the persons originated unchanged from the same gedcom
+- person merge may be a "comes before/comes after" decision at import time
+- person merge decisions can be deferred by storing two person entities under the same permaname
+  and letting the user make the before/after decision at a later time
+- multiple persons can be stored under the same permaname under 'entity1'..'entityN' blob names
+- copies the gedcom LICENSE if imported, copies the repo's LICENSE_DEFAULT if a newly-created person
+
+5) Family
+- direct represenation of the GEDCOM family concept
+- all imported families are stored in a standard JSON format under a "refs/heads/families/{permaname}" refs
+- there are multiple permanames for a family:
+  - one is designated as primary, all permanames are annotated internally to the family by a versioned hash function (for easy recomputation)
+  - primary permaname for family defaults to the sha256 hash of the parents' primary permanames in alphanumeric order
+  - alternate permaname for family is the sha256 hash of "<displayname>[ displayname][ marriage date]" (if there is marriage information, displaynames ordered by primary permaname alphanumeric ordering of parents)
+  - other alternate permanames are definable, as long as the context-free code for computing them is included under refs/heads/code
+  - permanames based on "displayname" state should not change when the person's name is updated, they are designed to produce collisions based on import data
+  - primary permaname should change if the parents' permanames are modified, or if a parent is replaced with a different person
+- includes person links for each person in each family position
+- includes optional "supersedes", "superseded-by", "derived-from", "same-as", and "not-same-as" link attributes (like person)
+- includes optional "prior-family" link attribute that tracks temporal household dissolution & recomposition
+- family merge is often not needed if the family originated unchanged from the same gedcom
+- family merge can be a "comes before/comes after" decision at import time, but is not as likely as person to fit this workflow
+- family merge decisions can be deferred by storing two family entities under the same permaname
+  and letting the user make the before/after decision at a later time
+- multiple families can be stored under the same permaname under 'entity1'..'entityN' blob names
+- copies the gedcom LICENSE if imported, copies the repo's LICENSE_DEFAULT if a newly-created record
+
+6) Link Attribute
+- link attributes always refer to BOTH primary permaname & state
+- link attributes are encoded similar to XFN to start
+
+7) Merge Strategies
+- merge comes in at least 4 flavors:
+  a) [import] alternate record storage + history linkage (recommended for automated import processes)
+  b) [post-import] "comes before/comes after" record replacement strategy for dealing with record reconciliation
+  c) [post-import] "pick correct values" record reconciliation strategy for dealing with partial truth from multiple sources (sets "derived-from" attribute(s))
+  d) [post-import] "disambiguation" record reconciliation strategy for separating records that are NOT the same person (sets "not-same-as" attribute(s))
+- of course anyone can do anything they please to their records, but these strategies seem to deserve automation support
+
+8) Record deriviation tracing
+- each of the following link attributes refers to another record via permaname+state reference
+- "supersedes" indicates that a person (or family) is a full, identical replacement for another (used to be able to react to remote merges)
+- "superseded-by" indicates that a static, not-to-be-further-edited  person (or family) is left behind after having been merged into the canonical record (used to detect conflicts between local edits & remote merge or vice versa)
+- "derived-from" indicates a clone-and-mutate to disambiguate a fully-merged record that represents two distinct historical persons or families (used to document manual record reconstruction efforts)
+- "same-as" indicates a more-tentative-than-merge attempt at establishing identity to allow for disparate efforts to proceed before attempting a full merge
+- "not-same-as" indicates a definitive statement that one person (or family) is NOT the same as another (used when extracting a half-merged entity that collided on a permaname)
+- "prior-family" indicates that a family has many of the same members of a prior family, but temporal household dissolution & recomposition require two different families to be tracked (allows for "current family" computations based on a directed graph of prior-family edges)
+
+9) Deletion of Records
+- person/family/gedcom delete comes in three flavors:
+  - "deref": I no longer care to track or maintain this person, if anyone has this person cloned, let them continue to maintain the record
+  - "hide": I want the record gone on any repo that follows mine, if they fetch from me, MAKE their record go away, dead-to-living transition uses this mechanism
+  - "delete": I want the record gone on any repo that follows mine, if they fetch from me, SUGGEST that their record go away
+- "hide" and "delete" stubs hang around for a longish-but-limited amount of time, and there is a mechanism that automatically cleans them up every so often
+
+
+GIT-GED REFS LAYOUT
+===================
+
+refs/heads/*:
+- stuff that can be cloned/forked
+refs/local/*:
+- dispensible stuff that is used for local import actions (not needed for collaboration)
+- hidden stuff that should not be published on a clone/fork
+
+refs/heads/master (fetchable, but non-mergeable):
+- README: simple documentation of git-ged, with pointer to software to parse/use
+
+refs/heads/content (fetchable, but non-mergeable):
+- META: last version of git-ged that wrote
+- INTENT: link to last intent
+- ROOTS: links to various person roots
+- ENTITIES: list of gedcom/person/family permaname+state links, may end up needing to be sharded for very large repos
+- LICENSE_DEFAULT: default license for any new records added or imported into to this repository, defaults to Creative Commons Share-alike
+- [non-versioned] CHANGELOG: contains up to last 100 edits performed, updated by git-ged commit
+
+refs/heads/intent (fetchable, but non-mergeable):
+- INTENT: stores the user's identity, single-line intent message, and date in the tree itself to capture "why"
+- MUST exist: if no intent is explicitly stored, init/import/edit must stub one in that describes the largest-scope action being taken
+- able to be as fine-grained and meticulous as the user wants to be, while allowing the user
+  the convenience of keeping the same intent over several small actions moving toward a large-time-scale goal
+- able to generate a feed of intents from here
+
+refs/heads/workspace (fetchable, but non-mergeable):
+- non-history-preserving workspace tree for pulling a subset of records into a filesystem for edit
+
+refs/heads/gedcoms/{permanames}:
+- ged1: the living-filtered gedcom file renamed to a standard filename
+- gedN: the living-filtered gedcom file renamed to a standard filename
+- contains no living data, as a result of "ingest" followed by "import"
+- gedX.META: link to intent; original file name & path; where/who the file came from; all permanames this gedcom was stored under (by permaname kind)
+- gedX.LICENSE: license for use of this gedcom as a whole, copied to individual persons/families at import time
+
+refs/local/gedcoms/{permanames}:
+- *may* contain living data, populated without filtering by "ingest"
+- ged1.ged: the raw gedcom file renamed to a standard filename
+- gedN.ged: the raw gedcom file renamed to a standard filename
+- pre-existing permanames get forwarded up to the new tree (collisions, yay!)
+- new permanames get created, non-colliding permanames don't get forwarded (gc'd by some other mechanism)
+- if the gedcom contains no living data, "import" can delete the refs/local refs
+- can coexist with refs/heads/gedcoms/{permaname} for a while as documentation of exactly what got imported
+- fetch/clone/fork does NOT include the original gedcom, just the "post-import" one (because only refs/heads comes along)
+
+refs/heads/persons/{permanames}:
+- entity1: the primary person in a standard JSON form
+- entityN: alternate, not-yet-merged person records
+- entityX.{format}: the primary person (or an alternate) in an alternate format
+- entityX.META: link to intent; link(s) to gedcom permanames
+- entityX.IDENTITY: optional "supersedes", "superseded-by", "derived-from", "same-as", and "not-same-as" link attributes; also any arbitrary XFNs to other permanames
+- entityX.LICENSE: license for use of this person, copied from gedcom at import time, or from repo's LICENSE_DEFAULT at non-import-creation time
+- commits on a person can easily be merged/fast-forwarded if history is shared and there are no textual conflicts
+- commits on two persons of the same permaname that do NOT share history can undergo person merge
+- merge commits set "supersedes" and "superseded-by" link attributes to allow post-merge traceability
+- merging of META takes a "most recent intent / union" approach
+- merging of IDENTITY takes a "union with conflict detection & manual resolution" approach
+- merging of LICENSE takes the more restrictive license by default
+
+refs/local/persons/{permanames}:
+- non-public person record, behaves like person in every other respect
+- typically a person record should exist under EITHER refs/local OR refs/heads
+- if both exist, the refs/heads record is used exclusively
+
+refs/heads/families/{permanames}:
+- entity1: the primary family in a standard JSON form
+- entityN: alternate, not-yet-merged family records
+- entityX.{format}: the primary person (or an alternate) in an alternate format
+- entityX.META: link to intent; link(s) to gedcom permanames
+- entityX.IDENTITY: optional "prior-family", "derived-from", "supersedes", "superseded-by", "same-as", and "not-same-as" link attributes; also any arbitrary XFNs to other permanames
+- entityX.LICENSE: license for use of this person, copied from gedcom at import time, or from repo's LICENSE_DEFAULT at non-import-creation time
+- commits on a family can easily be merged/fast-forwarded if history is shared and there are no textual conflicts
+- commits on two families of the same permaname that do NOT share history can undergo family merge
+- merging of META takes a "most recent intent / union" approach
+- merging of IDENTITY takes a "union with conflict detection & manual resolution" approach
+- merging of LICENSE takes the more restrictive license by default
+
+refs/local/families/{permanames}:
+- non-public family record, behaves like person in every other respect
+- typically a family record should exist under EITHER refs/local OR refs/heads
+- if both exist, the refs/heads record is used exclusively
+
+

data/lib/git-ged.rb

@@ -0,0 +1,53 @@
+$:.unshift File.dirname(__FILE__) # For use/testing when no gem is installed
+
+# core
+require 'fileutils'
+require 'time'
+
+# stdlib
+require 'logger'
+require 'digest/sha1'
+
+# third party
+require 'grit'
+
+# internal requires
+
+# common libraries
+require 'git-ged/repo'
+
+# git-like repo interaction
+require 'git-ged/cli'
+require 'git-ged/init'
+
+# internal support classes
+
+module GitGed
+  VERSION = '0.0.2'
+
+  class << self
+
+    def version
+      VERSION
+    end
+
+    attr_accessor :debug
+
+    def grit_debug= onoff
+      Grit.debug = onoff
+    end
+
+    # The standard +logger+ for debugging git-ged calls - this defaults to a plain STDOUT logger
+    attr_accessor :logger
+
+    def log(str)
+      logger.debug { str }
+    end
+  end
+
+  self.debug = false
+  self.grit_debug = false
+
+  @logger ||= ::Logger.new(STDOUT)
+
+end

data/lib/git-ged/cli.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+require 'git-ged'
+require 'optparse'
+require 'subcommand'
+
+module GitGed
+  class CLI
+
+    include Subcommands
+
+    # patch until subcommand 1.0.7 comes out
+    attr_accessor :appname
+
+    def initialize
+      @options = {}
+
+      self.appname = "git ged"
+      global_options do |opts|
+        opts.banner = "Usage: #{appname} [options] [subcommand [options]]"
+        opts.separator ""
+        opts.separator "Global options are:"
+        opts.on("-v", "--[no-]verbose", "Show git-ged & grit debug") do |v|
+          GitGed.debug = v
+          GitGed.grit_debug = v
+        end
+      end
+      add_help_option
+
+      command :init do |opts|
+        opts.banner = "Usage: #{appname} init [-m msg] [repo]"
+        opts.description = "Initializes a new git-ged repo"
+        opts.separator ""
+        opts.separator "Options:"
+        opts.on "-m MESSAGE", "--message MESSAGE" do |msg|
+          @options[:message] = msg
+        end
+      end
+    end
+
+    def run
+      cmd = opt_parse()
+      if cmd
+        Repo.new.send cmd, ARGV, @options
+      else
+        puts global_options { |opts| opts }
+      end
+    end
+
+  end
+end

data/lib/git-ged/init.rb

@@ -0,0 +1,12 @@
+module GitGed
+  class Repo
+
+    ##
+    # Initializes a new git-ged repo
+    def init(args, options={})
+      system "git init -q #{args.map{|s| "\"#{s}\"" }.join(" ")}"
+      GitGed.log "Created new git-ged repo"
+    end
+
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: git-ged
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- John Sumsion
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: grit
+  requirement: &14236180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *14236180
+- !ruby/object:Gem::Dependency
+  name: subcommand
+  requirement: &14235700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.6
+  type: :runtime
+  prerelease: false
+  version_requirements: *14235700
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: &14235320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *14235320
+description: git-ged is a Ruby toolset for managing genealogical data (GEDCOM) inside
+  a Git repository.
+email: jdsumsion@gmail.com
+executables:
+- git-ged
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+- LICENSE.grit
+- TODO
+- layout.txt
+files:
+- LICENSE
+- LICENSE.grit
+- README.md
+- Rakefile
+- TODO
+- bin/git-ged
+- git-ged.gemspec
+- layout.txt
+- lib/git-ged.rb
+- lib/git-ged/cli.rb
+- lib/git-ged/init.rb
+- lib/git-ged/repo.rb
+homepage: http://github.com/jdsumsion/git-ged
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 2
+summary: GEDCOM plugin for Git
+test_files: []