Collaborating with Family Members using GEDitCOM II and GEDitCOM

One challenge in genealogy research is working together with friends and family members and keeping everyone up-to-date with the latest research results. If everyone in your collaboration group has either GEDitCOM II or GEDitCOMGEDitCOM II, the simplest approach is to use the built-in feature to merge records using "Universally Unique IDs" (UUIDs). To learn how to use this method:

  1. Open GEDitCOM II or GEDitCOM help window
  2. Click on "Opening, Saving, Merging" in the help index on the left.
  3. Click on "Synchronizing GEDPKG Files in Collaborative Genealogy Projects" and read that help information.

If the above method works for you, that method is best. This tutorial gives two alternate solutions for collaborations. In brief, these methods use existing tools for software development collborations but replace the software code by genealogy files and multimedia objects. The two tools are called github and Subversion and explained in the following two sections.

Collaborating with GitHub

A popular tool for software development is GitHub and it is easy to use for genealogy too. The following is an outline of the process. You are referred to GitHub for more details on any step.

  1. Create an account on GitHub. You can create free versions or paid versions with more options. A free version might be enough and lets you create both public and private repositories (private is certainly best for genealogy data).
  2. While creating an account, download GitHub Desktop for MacOS. It is the best way to create and edit your genealogy repositories. Open GitHub Desktop and sign into your account.
  3. In your repository list in GitHub Desktop, click "Add" button and select "Create New Repository..." from the popup menu. Pick a name, enter a short description, pick a path to save on your computer (often a "GitHub" folder but if using GEDitCOM it must be a folder in your genealogy workspace folder), and check box to include ReadMe.md file. When done, click "Create Repository."
  4. The repository will start only on your computer. To get to your account on GitHub, view the repository and click "Publish." You can chose to make it public (anyone in the world can see) or private (only you and collaborators can see).
  5. Now fill your repository with files:
    • If you will only put one file in the repository, copy that file along with multimedia library folders to your repository folder.
    • If you want multiple files in the same repository, create a folder for each one and then copy the file and its multimedia to that folder. This keeps the different files separated in the repository.
  6. When you view the repository back in GitHub Desktop, you will see all the files you added in the previous step. To get them into your account on GitHub:
    1. Enter brief text and optional comments and click "Commit To Master."
    2. The first step commits to master in the local copy, but not on GitHub. To copy there, click "Push to Origin."
  7. Now start editing files:
    • To edit your genealogy data, open the file now in your GitHub folder in GEDitCOM II or GEDitCOM and edit as usual. Note that since you will do all editing on this file, you can delete the version you originally copied to your repository.
    • It is a good idea to edit the ReadMe.md file created above when you created the repository. The contents of this file is displayed to collaborators when they view your repository on GitHub. The "md" stands for mark down files that makes it easier to create html content. You can visit getting started and basic syntax for help on editing mark down files.
    • Whenever you want to save your edits to your account on GitHub, use the commit and push methods as in the previous step.
  8. See below to clone a sample repository created and edited by the above steps.

The above steps create a repository that only you can edit. To collaborate with others, you have to invite them as collaborators, which you can do by viewing you repository on GitHub. Collaborators can then clone the project and work along with you on the genealogy research. The basic steps are:

A Sample GitHub Repository

To see a sample GitHub repository with a GEDitCOM II file (which is compatible with GEDitCOM) you can clone a repository with the "Windsors" genealogy file that comes with GEDitCOM II as a sample file (but not with GEDitCOM). The URL for this repository is:

https://github.com/nairnj/Windors-GEDitCOM

Two methods to clone it are:

  1. Use the File→Clone Repository command in GitHub Desktop, enter above URL, and choose a local folder for saving the repository.
  2. Go to the repository on GitHub, click the green "<> Code" button, and pick a cloning method from the "Local" tab.

The cloned respository will have the "Windors.gedpkg" file you can open in GEDitCOM II or GEDitCOM.

Collaborating with Subversion

Another tool for developers is Subversion (or svn) and GEDitCOM II cooperatesboth GEDitCOM II and GEDitCOM cooperate with svn tools. Subversion (or svn) used to be installed automatically in MacOS, but now has to be installed manually. Before using this tutorial, you have to install command line tools and then separately install Subversion. Because this method varies in each now MacOS, you can google the latest options for your MacOS. The rest of this tutorial assumes those installations have been done and gives command-line tools for all svn tasks, which are all entered using the Terminal app. For those not comfortable with command-line tools, all these tasks can be done instead by purchasing a visual front end for svn tasks. One excellent front end, or Subversion client, is called Versions. If you do use command-line tools, you can read all you need to know in the free on-line Subversion book. The most common commands are described in this tutorial.

The tasks for collaborating using svn are:

Create a Repository for Your Genealogy Data

The first task is to set up a repository for your data. The best choice here is a cloud-computing server that is accessible by all those collaborating on the project. If you have your own server, you may be able to set one up yourself. Otherwise, the best option is to create an account on a server designed for Subversion projects. One excellent web site is Beanstalk. They provide secure storage, automatic backup, and have a package for anyone's needs. You can get started with a free account, which is limited to 100 MB of storage. You can expand to more features as needed.

Whether you use Beanstalk or some other service, the first step is to create an empty repository. This task will usually be done by the tools in the service you select. In Beanstalk, you will get an account name, such as MyAccount, a password for that account, and you can create a repository with another name, such as MyTree. The repository will have its own URL for svn tasks, such as:

	http://MyTree.svn.beanstalkapp.com/MyTree/

The default Subversion repository will have three folders in this URL with the following names:

	MyTree/branches
	MyTree/tags
	MyTree/trunk

The branches folder is used by software developers to try adding new features to applications; it may not be that useful in genealogy. The tags folder is used to store stable versions of your project for easy recall later. The trunk folder is where you store your main project and all your genealogy data.

Import Initial Genealogy Files into the Repository

The following steps are needed to prepare your genealogy data for upload to the new repository:

  1. Create a new folder for your genealogy file.
  2. Make sure all multimedia objects are stored in that same folder or within any subfolder in that folder. If needed, you can open the "Multimedia Options" panel (in the "Tree" menu) and use the "Consolidate Multimedia Objects" section in the "Options" tab. See the GEDitCOM II or GEDitCOM help for details on this tool.
  3. Delete all thumbnail images (because they are not needed in the repository and only make it larger). To delete them, click the "Delete All" button in the "Multimedia Thumbnails" section of the "Options" tab of the "Multimedia Options" panel. (not needed for GEDitCOM)
  4. Save the file
  5. Quit GEDitCOM II or GEDitCOM

Your genealogy data are now ready for importing into your repository. The steps are:

  1. Start the Terminal app
  2. Navigate to the folder containing the genealogy folder created above - here that folder's name is assumed to be InitialGeneo.
  3. Use the svn command: 
    	svn import -m "Initial Import" InitialGeneo http://MyTree.svn.beanstalkapp.com/MyTree/trunk \
	     --username MyAccount
  4. You will be asked to supply a password and then the entire contents of the InitialGeneo folder will be imported into your repository. It is now ready for use.

Check Out Working Copies of Your Genealogy Data

The basic work flow for an svn project is to check out a working copy of the project, make changes as you work on the research, and then commit those changes back to the repository. If someone else make changes, you can receive those changes by updating your working copy. This section explains how to check out a working copy.

The import in the previous section, uploads your files to the repository, but does not convert you initial copy into a working copy. To get a working copy, check one out as follows:

  1. Start the Terminal app
  2. Navigate to the folder you want to contain your working copy (for GEDitCOM, this folder should be within your genealogy workspace folder, or be the workspace folder itself)
  3. Use the svn command: 
        svn checkout http://MyTree.svn.beanstalkapp.com/MyTree/trunk LocalTree --username MyAccount
  4. You will be asked for a password and all files will be downloaded into a new folder called LocalTree
  5. Open the genealogy file in the LocalTree folder in GEDitCOM II or GEDitCOM and start working on your research

The only thing optional in the check out command line is the "LocalTree" name just before your username. This entry will be the name of the folder created in the current folder to hold all the genealogy files and will be your working copy folder and can be any name you want (it need not match the repository name).

Make Changes and Commit Results

As you make changes and add multimedia objects, you will want to save the new data in the repository. This step is done by committing your changes. The steps are:

  1. Start the Terminal app
  2. Navigate to your working copy folder
  3. Use the svn command: 
        svn commit -m "describe the changes"
  4. The quoted text is required, but can be any short text to describe the recent changes.
  5. The above command will commit all changes. You can commit changes to individual files by adding the file name(s) to the commit command if desired.

If you add multimedia objects to your data, you need to add their files and then commit. To add a file, use the command:

    svn add Path/To/MultimediaObject

where Path/To/MultimediaObject is a relative path from your current directory in the Terminal app to the file that needs to be added. The add command will mark a file for adding, but will not add it your the repository until your next commit, as done by the commit mnethod described above.

If you add several multimedia objects, you may forget which ones need to be added to the repository. This problem is solved with the following command in the main folder of the working copy:

    svn status

Any files found in the working copy, but not found in the repository will be listed with a "?". These files are the ones that need to be added. (Note: you can ignore a "thumbs" directory within the gedpkg file (if there); that directory contains multimedia thumbnails and it does not need to be in the repository because they are recreated whenever needed.)

Update Results when Someone Else Changes the Data

Whenever one person commits changes to the repository, all others with working copies can update their copy for the new data as follows:

  1. Start the Terminal app
  2. Navigate to your working copy folder
  3. Use the svn command: 
        svn update
  4. The above command will update all changes. You can update changes to individual files by adding the file name(s) to the update command if desired.