Sort, Save, and Do Versioning Command

To get started on collborating with others (or yourself on multiple computers) using git or svn, see this on-line tutorial. Once you have started, this extension provides features to make the process more reliable and to simplify a few common tasks.

Reason for this Extension

Versioning tools, such as git or svn, work mostly by comparing changes in text files between a working copy on your computer and an official copy stored in a repository. The tools work with "packages" having extension .gedpkg, because those files are actually folders that contain text files. The key text file is an internal GEDCOM file. When you save changes in , the new GEDCOM file has records of each type in the order they are displayed in the main index window. A possible problem arises if:

1. You open a file and change sort order in the index window
2. Save the file (even if no other edits) in the new sort order

Version control will think the saved file has a large number of changes even though nothing has changed. A solution to this problem is to always revert to a standard sort order before saving the file and using a versioning command. This extension automates that task.

Using the Extension

Start by viewing a file that is under version control and choose this extension. The extension will first sort all record types use a consistent sorting order and then save the file. The file is then ready for version control commands. The extension options are:

1. Pick the git or svn version command you would like to use and click "OK". If you prefer to do version control in other software, or if a command you need is not listed, click "Cancel" and move to other software with the newly-saved file.
2. If you pick a "commit" option, you will be asked for a brief description of the changes being committed. When using git, you can enter multiple lines of description by using "\\" to start a new line. The first line is summary of the changes and any additional lines give more details.
3. Choose to have the extension "Run" the command for you or just have it "Display" appropriate command-line text. If you choose "Run", the command will execute as a subprocess and final results will be displayed in the extension's output. If you choose "Display", the output will have command-line text.GEDitCOM can only display the needed command-line messages. You can copy and paste those command lines into the Terminal app to run them.

Details on git Commands

The git commit command only commits changes in your local repository. In contrast, the git commit/push command both commits changes and pushes those changes to your remote git project. The "push" step, however, requires authentication and this extension does not handle that process. If you get an error on the "push" step, you can try to adjust your project to make it work (hint: post the error message into ChatGPT to get ideas for authentication options). Alternatively, you can use this extension for the git commit command (which works on your local copy and therefore does not need authentication) and then use other software to push the changes to your remote project.

The git pull command updates your local copy and then closes and reopens your file to make sure the changes are in the copy currently being viewed in . The git status command lists difference between your working copy and the repository.

Note that before committing changes, this extension will invoke git add . to stage changed files. If this process might mistakenly add files you do not wanted tracked, you should clean up your working copy before committing. The git status command will list files that might be unwanted.

Note that the push in git commit/push command and the git pull command both assume you are working with a "main" branch and the remote copy is called "origin" (these are defaults settings for git projects). If you have different settings you have to either edit this extension in GEDitCOM Editor to change them or switch to other software to run custom commands. When editing the extension, change #branch and #origin variables near the beginning to your settings.

Details on svn Commands

The svn commands will commit changes, update to lastest copy, or report status of your working copy. An authentication problem arises if you configured your svn repository to require a password. To automate inclusion of svn password, which might differ for different projects, you can do the following:

• Create a lightly-encrypted version of your svn passoword as follows:
  1. Cut n=0 to 8 characters from the start of the password and paste at the end.
  2. Append one character equal to n+1 (which will be 1 to 9) to the end of the password
  3. Type any 3 characters at the beginning of the password.
  4. For example, the password MySVNPassword could rearrange to GITPasswordMySVN6 (i.e., move "MySVN" to the end, append "6", and randomly paste "GIT" to the start of the password).
• Add a "User Reference Number" to the main submitter record. Set its contents to the rearranged password and its "Type" field to svn.

This process is not particularly secure. If you are concerned, you should just switch to other svn software after running this extension just to get correct sort order. If someone happens to find your GEDCOM file outside a working copy and with that main submitter, they likely will not gain access to your remote repository. They will neither know its location nor how to unscramble the password.

Note that svn commit command will not add new files (such as new multimedia files) to your respository. You will need to manually add them with other software before using this extension to commit all changes. You can use svn status command to look for files that need adding.