phraseapp_updater 0.1.7 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b0d34620e813a3d8381bb9e69718c4eddf00861c
-  data.tar.gz: 83376f665f0c2a2db922f5297f2a29890700be54
+SHA256:
+  metadata.gz: a9a01be297b026f1bcf98b8337306f7dd5340f15bd21dc7264ccf78aff82d242
+  data.tar.gz: 6c8cd2024db62795d678b148621dd3556e5a7771daa33076e004a00d68bde88e
 SHA512:
-  metadata.gz: e17e637e811441675d66c88a948913ba8526a014934405889b31422200991e66cc68d8cc9e0a733d99cd98f87e7b0f6f051fa0b358d5d15f3af8f47ad6eb28c3
-  data.tar.gz: 4b3e48725db68140f04d6c12f836ce82e6514151b652525331925ea3a8b690209fdf2d67ff5c6594c2f0b75c7629ffd3e1254ca1a191ff43228edc4e224f101a
+  metadata.gz: aab7ed4136379375aa89531722ce00af0d7027f0433ad0d77f2793a855966f59f286ad3f154f71c4bfe48a604275f72805e615f3be65e4abf58390f025f7f058
+  data.tar.gz: 83aae79c39f421c21deed218e8c0bfa0dcfbbe663ec49520cda9dbd675268728877ce665aae5150d45438ccb5d241cfb23995d8c3168eb237c28689e5b37639c

data/Gemfile

@@ -2,4 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in phraseapp_updater.gemspec
 gemspec
+gem 'byebug'
 

data/README.markdown

@@ -2,34 +2,28 @@
 
 [![Build Status](https://travis-ci.org/iknow/phraseapp_updater.svg?branch=master)](https://travis-ci.org/iknow/phraseapp_updater)
 
-**Version** 0.1.7
-
-This is a tool for merging PhraseApp locale data with locale data
-committed in your project.
-
-It can perform three-way merges of [PhraseApp](https://phraseapp.com) locale data with locale data commited to your application.
-It can also pull from PhraseApp, ignoring missing keys (this is very
-useful for using "unverified" status for marking a translation as a
-draft).
-
-Our current workflow has localizers working on a `master` project on
-PhraseApp. This regularly gets pulled into the `master` branch of our
-application and released. This branch is for "maintenance" localizations:
-ongoing translations of existing locale keys.
-
-However, we also introduce, remove, and change locale data by merging in
-feature branches to `master`. When we do this, we want to update the
-`master` PhraseApp project with the data newly-commited to our `master`
-branch. PhraseApp provides [APIs](https://phraseapp.com/docs/api/v2/) and a [Ruby gem](https://github.com/phrase/phraseapp-ruby) for accessing
-them, but the API only allows either a) completely overwriting
-PhraseApp's data or b) reapplying PhraseApp's data on top of the
-uploaded data.
-
-What we want instead is a three way merge where the committed data wins
-on conflict. Non-conflicting changes on PhraseApp are preserved, while
-changes on both sides take the committed data. The result of the merge
-is then sent to PhraseApp, keeping it up-to-date with the newest commit
-of `master`.
+**Version** 2.0.0
+
+This is a tool for managing synchronization between locale data in
+[PhraseApp](https://phraseapp.com) and committed in your project. It can perform
+JSON-aware three-way merges with respect to a common ancestor, and maintains a
+record of the common ancestor on PhraseApp using tags.
+
+Our workflow considers localization data stored on PhraseApp to be a working
+copy for a given branch. We expect developers working on the code and
+translators working on PhraseApp to both be able to make changes and have them
+integrated.
+
+PhraseApp provides [APIs](https://phraseapp.com/docs/api/v2/) and a [Ruby
+gem](https://github.com/phrase/phraseapp-ruby) for accessing them, but the API
+only allows either a) completely overwriting PhraseApp's data with local data or
+b) reapplying PhraseApp's data on top of the local data. Neither of these cases
+is appropriate for integrating changes made on both sides.
+
+What we want instead is a three way merge where the committed data wins on
+conflict. Non-conflicting changes on PhraseApp are preserved, while changes to
+the same key on both sides take the committed data. The result of the merge is
+then applied to both sides, keeping them up to date with each other.
 
 This is especially important when removing keys. Imagine we have the
 following, no-longer useful key:
@@ -48,9 +42,8 @@ unused:
   zero: No unused's
 ```
 
-And in our feature branch, we remove it. The result we want is that the
-key completely disappears, instead of getting a result like either of
-the above.
+And in our feature branch, we remove it. The result we want is that the key
+completely disappears, instead of getting a result like either of the above.
 
 ## Installation
 
@@ -80,68 +73,79 @@ Or install it yourself as:
 CLI
 ---
 
-**Push**
+**Setup**
 
-`phraseapp_updater push` operates on two directories and your PhraseApp API
-data. The two directories should contain the previous revision of your
-locale files from PhraseApp and the latest revision of the same files
-committed to your application's respository.  These will be used in the
-merge with the files on PhraseApp.
+`phraseapp_updater setup` creates and initializes a PhraseApp project
+corresponding to your branch. It must be provided with the current git revision
+of the branch and the path to the locale files.
 
 ```
-phraseapp_updater push --new_locales_path="/data/new", --previous_locales_path="/data/previous" --phraseapp_api_key="yourkey" --phraseapp_project_id="projectid --file_format=json"
+phraseapp_updater setup --phraseapp_project_name="yourbranch" --parent_commit="yourhash" --phraseapp_api_key=yourkey" path_to_locales
 ```
 
-The arguments provided to the command can also be specified as shell
-variables:
+**Synchronize**
+
+`phraseapp_updater synchronize` synchronizes a git remote branch with its
+corresponding PhraseApp project, incorporating changes from each side into the
+other. If both sides were changed, a three-way merge is performed. The result is
+uploaded to PhraseApp and committed and pushed to the git remote as appropriate.
+
+The option `--no_commit` may be provided to restrict changes to the PhraseApp
+side. If specified, then in the case that the branch was modified, the merge
+result will be uploaded to PhraseApp and the common ancestor updated to the
+branch head.
 
 ```
-PA_NEW_LOCALES_PATH
-PA_PREVIOUS_LOCALES_PATH
-PA_API_KEY
-PA_PROJECT_ID
-PA_FILE_FORMAT
+phraseapp_updater synchronize <checkout_path>
 ```
 
-Additionally, PhraseApp credentials can be loaded from a
-`.phraseapp.yml` file, specified with `--config-file-path`
+**Download**
+
+`phraseapp_updater download` downloads and normalizes locale files from
+PhraseApp, saving them to the specified location. The revision of the recorded
+common ancestor is printed to standard out.
 
-**Pull**
+```
+phraseapp_updater download --phraseapp_project_id="yourid" --phraseapp_api_key="yourkey" target_path
+```
 
-`phraseapp_updater pull` pulls data down from your PhraseApp project.
-However, when keys are missing from the PhraseApp data, it restores them
-(if present) from the files at fallback path provided. This allows you
-to mark keys as "unverified" on PhraseApp, meaning you don't pull in
-draft translations, while allowing you to keep the current version of
-that translation.
+**Upload**
 
-If you want to pull without this fallback behavior, PhraseApp's [client](https://phraseapp.com/docs/developers/cli/)
-is the best tool to use.
+`phraseapp_updater upload` uploads normalized locale files from your branch to
+PhraseApp and resets the recorded common ancestor to the specified revision.
 
 ```
-phraseapp_updater pull --fallback_path="/data/app/locales" --phraseapp_api_key="yourkey" --phraseapp_project_id="projectid --file_format=json""
+phraseapp_updater upload --phraseapp_project_id="yourid" --phraseapp_api_key="yourkey" path_to_locales
 ```
 
-The PhraseApp data passed to the command can also be specified as shell
-variables:
+**Update Parent Commit**
+`phraseapp_updater update_parent_commit` records a new common ancestor on
+PhraseApp without changing the locales.
 
 ```
-PA_API_KEY
-PA_PROJECT_ID
-PA_FILE_FORMAT
+phraseapp_updater update_parent_commit --phraseapp_project_id="yourid" --phraseapp_api_key="yourkey" --parent_commit="yourhash"
 ```
 
-Additionally, PhraseApp credentials can be loaded from a
-`.phraseapp.yml` file, specified with `--config-file-path`
+**Merge**
 
-Ruby
----
+`phraseapp_updater merge` performs a content-aware three-way merge between
+locale files in three directories: `ancestor_path`, `our_path`, and
+`their_path`. In the case of conflicts, the changes from `our_path` are
+accepted. The results are normalized and written to the path specified with
+`to`.
 
-`PhraseAppUpdater.push` and `PhraseAppUpdater.pull` are analogous to the command line versions:
+```
+phraseapp_updater merge ancestor_path our_path their_path --to target_path
+```
 
-```ruby
-PhraseAppUpdater.new("api_key", "project_id", "file_format").push("previous/path", "current/path")
-PhraseAppUpdater.new("api_key", "project_id", "file_format").pull("fallback/path")
+
+**Diff**
+
+Performs a content-aware diff between locale files in two directories. Returns
+with exit status 1 or 0 to signal differences or no differences respectively
+
+```
+phraseapp_updater diff path1 path2
 ```
 
 
@@ -157,8 +161,11 @@ https://gist.github.com/kevingriffin/d59821446ce424a56c7da2686d4ae082
 
 If you'd like to contribute, these would be very helpful!
 
-* Separating downloading and resolving data from PhraseApp from pushing
-  back up to it, to enable different kinds of workflows.
+* We'd like to use "unverified" translations on PhraseApp as the equivalent of
+  an unstaged working copy. For this to work, we need to be able to recover
+  previous translations at the same key. While PhraseApp doesn't itself keep
+  this history, we could do this by restoring the absent keys from the diff
+  between verified and unverified download from the common ancestor.
 * Expose the changed files on the command line.
 * Checking if PhraseApp files changed during execution before upload, to reduce the race condition window.
 * More specs for the API and shell.

data/bin/phraseapp_common.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+
+# Set up a working directory
+working_directory=$(mktemp -d -t phraseapp)
+
+function cleanup_working_directory(){
+    rm -rf "${working_directory}"
+}
+
+trap "cleanup_working_directory" EXIT SIGINT
+
+function make_temporary_directory() {
+    mktemp -d "${working_directory}/XXXXXXXX"
+}
+
+function make_tree_from_directory() {
+    local directory filename object
+    directory="$1"
+
+    if [ ! -d "$directory" ]; then
+        echo "Error: directory not found: '${directory}'" >&2
+        exit 1
+    fi
+
+    for file in "$directory"/*; do
+        if [ -d "$file" ]; then
+            echo "Error: make_tree_from_directory cannot create recursive tree: '${file}'" >&2
+            exit 1
+        fi
+
+        filename=$(basename "${file}")
+        object=$(git hash-object -w "${file}")
+        printf "100644 blob %s\\t%s\\n" "${object}" "${filename}"
+    done | git mktree
+}
+
+
+function extract_commit() {
+    extract_files "$1:${PREFIX}"
+}
+
+function extract_files() {
+    local path
+    path=$(make_temporary_directory)
+
+    git archive --format=tar "$1" | tar -x -C "${path}"
+
+    echo "${path}"
+}
+
+function locales_changed() {
+    ! phraseapp_updater diff --quiet "$1" "$2"
+}
+
+function tree_changed() {
+    ! git diff-tree --quiet "$1" "$2"
+}
+
+function replace_nested_tree() {
+    local root path tree
+    root="$1"
+    path="$2"
+    tree="$3"
+
+    while [ "$path" ]; do
+        leaf_name=$(basename "$path")
+        path=$(dirname "$path")
+        [ "$path" = "." ] && path=''
+
+        # replace `leaf_name` in `path` with `tree`, yielding new tree
+        tree=$(git ls-tree "${root}:${path}" | \
+                   replace_child_in_tree "${leaf_name}" "${tree}" | \
+                   git mktree)
+    done
+
+    echo "$tree"
+}
+
+function replace_child_in_tree(){
+    ruby -pe 'BEGIN { file, tree = ARGV.shift(2) };
+              gsub(/ [0-9a-z]{40}\t/, " #{tree}\t") if /\t#{file}$/' "$@"
+}

data/bin/phraseapp_updater

@@ -1,89 +1,202 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require 'thor'
 require 'phraseapp_updater'
 
 class PhraseAppUpdaterCLI < Thor
-  desc "push", "Update PhraseApp project via a 3-way merge with local locale files and PhraseApp data."
-  option :new_locales_path,                type: :string, desc: "Path to newest revision of local files. Shell variable: PA_NEW_LOCALES_PATH"
-  option :previous_locales_path,           type: :string, desc: "Path to previous revision of local files. Shell variable: PA_PREVIOUS_LOCALES_PATH"
-  option :phraseapp_api_key,               type: :string, desc: "PhraseApp API key. Shell variable: PA_API_KEY"
-  option :phraseapp_project_id,            type: :string, desc: "PhraseApp project ID. Shell variable: PA_PROJECT_ID"
-  option :config_file_path,                type: :string, desc: "Path to .phraseapp.yml config file to read API key and project ID."
-  option :store_results_path,              type: :string, desc: "Path to write the resolved files. Shell variable: PA_STORE_RESULTS_PATH"
-  option :store_phraseapp_originals_path,  type: :string, desc: "Path to write the files downloaded from PhraseApp before the merge. Shell variable: PA_STORE_PHRASEAPP_ORIGINALS_PATH"
-  option :file_format,                     type: :string, desc: "Filetype of localization files."
+  class_option :default_locale, type: :string, default: 'en',   desc: 'PhraseApp default locale'
+  class_option :file_format,    type: :string, default: 'json', desc: 'Filetype of localization files.'
+
+  desc 'setup <locale_path>',
+       'Create a new PhraseApp project, initializing it with locale files at <locale_path>. the new project ID is printed to STDOUT'
+  method_option :phraseapp_api_key,      type: :string, required: true, desc: 'PhraseApp API key.'
+  method_option :phraseapp_project_name, type: :string, required: true, desc: 'Name for new PhraseApp project.'
+  method_option :parent_commit,          type: :string, required: true, desc: 'git commit hash of initial locales'
+
+  def setup(locales_path)
+    validate_readable_path!('locales', locales_path)
 
-  def push
-    phraseapp_api_key, phraseapp_project_id, file_format = load_phraseapp_configuration(options)
+    handle_errors do
+      updater, project_id = PhraseAppUpdater.for_new_project(
+                 options[:phraseapp_api_key],
+                 options[:phraseapp_project_name],
+                 options[:file_format],
+                 options[:parent_commit])
+
+      updater.upload_directory(locales_path)
+
+      puts project_id
+    end
+  end
 
-    new_locales_path = options.fetch(:new_locales_path, ENV["PA_NEW_LOCALES_PATH"]).to_s
-    validate_readable_path!('new_locales_path', new_locales_path)
+  desc 'synchronize <git_checkout_path>',
+       'Synchronize locales in PhraseApp with '
+  method_option :phraseapp_api_key,    type: :string, required: true,            desc: 'PhraseApp API key.'
+  method_option :phraseapp_project_id, type: :string, required: true,            desc: 'PhraseApp project ID.'
+  method_option :branch,               type: :string, required: false,           desc: 'Name of (remote) git branch to synchronize'
+  method_option :remote,               type: :string, required: false,           desc: 'Name of git remote to synchronize with'
+  method_option :prefix,               type: :string, default: 'config/locales', desc: 'Path prefix in git branch for locale files'
+  method_option :no_commit,            type: :boolean, default: false,           desc: 'Do not commit merge results to the branch'
+
+  def synchronize(checkout_path)
+    validate_readable_path!('checkout path', checkout_path)
+    Dir.chdir(checkout_path)
+
+    ENV['PHRASEAPP_API_KEY']    = options[:phraseapp_api_key]
+    ENV['PHRASEAPP_PROJECT_ID'] = options[:phraseapp_project_id]
+    ENV['FILE_FORMAT'] = options[:file_format]
+    ENV['NO_COMMIT']   = options[:no_commit] ? 't' : 'f'
+    ENV['PREFIX']      = options[:prefix]
+    ENV['BRANCH']      = options.fetch(:branch) { sh('git name-rev --name-only HEAD').chomp }
+    ENV['REMOTE']      = options.fetch(:remote) { sh("git config branch.#{ENV['BRANCH']}.remote").chomp }
+
+    shell_script_path = File.join(__dir__, 'synchronize_phraseapp.sh')
+    exec(shell_script_path)
+  end
 
-    previous_locales_path = options.fetch(:previous_locales_path, ENV["PA_PREVIOUS_LOCALES_PATH"]).to_s
-    validate_readable_path!('previous_locales_path', previous_locales_path)
+  desc 'download <target_path>',
+       'Download and renormalize locale files from PhraseApp to <target_path>'
+  method_option :phraseapp_api_key,    type: :string, required: true, desc: 'PhraseApp API key.'
+  method_option :phraseapp_project_id, type: :string, required: true, desc: 'PhraseApp project ID.'
 
-    store_results_path = options.fetch(:store_results_path, ENV["PA_STORE_RESULTS_PATH"]).to_s
-    validate_writable_path!('store_results_path', store_results_path)
+  def download(target_path)
+    validate_writable_path!('target path', target_path)
 
-    store_phraseapp_originals_path = options.fetch(:store_phraseapp_originals_path, ENV["PA_STORE_PHRASEAPP_ORIGINALS_PATH"]).to_s
-    validate_writable_path!('store_phraseapp_originals_path', store_phraseapp_originals_path)
+    handle_errors do
+      updater = PhraseAppUpdater.new(
+        options[:phraseapp_api_key],
+        options[:phraseapp_project_id],
+        options[:file_format])
 
-    begin
-      result = PhraseAppUpdater.new(phraseapp_api_key, phraseapp_project_id, file_format).push(previous_locales_path, new_locales_path)
+      updater.download_to_directory(target_path)
+      parent_commit = updater.read_parent_commit
 
-      unless store_results_path.empty?
-        write_locale_files(store_results_path, result.resolved_files)
+      if parent_commit.nil?
+        STDERR.puts 'Error: Locales downloaded from phraseapp, but parent commit details missing'
+        exit(1)
       end
 
-      unless store_phraseapp_originals_path.empty?
-        write_locale_files(store_phraseapp_originals_path, result.original_phraseapp_files)
+      puts parent_commit
+    end
+  end
+
+  desc 'upload <locale_path>',
+       'Renormalize and upload locale files at <locale_path> to PhraseApp, replacing current contents.'
+  method_option :phraseapp_api_key,    type: :string, required: true, desc: 'PhraseApp API key.'
+  method_option :phraseapp_project_id, type: :string, required: true, desc: 'PhraseApp project ID.'
+  method_option :parent_commit,        type: :string, required: true, desc: 'git commit hash of locales being uploaded'
+
+  def upload(source_path)
+    validate_readable_path!('source path', source_path)
+
+    handle_errors do
+      updater = PhraseAppUpdater.new(
+        options[:phraseapp_api_key],
+        options[:phraseapp_project_id],
+        options[:file_format])
+
+      updater.upload_directory(source_path)
+      updater.update_parent_commit(options[:parent_commit])
+    end
+  end
+
+  desc 'update_parent_commit', 'Record a new merge-base on PhraseApp without changing contents.'
+  method_option :phraseapp_api_key,    type: :string, required: true, desc: 'PhraseApp API key.'
+  method_option :phraseapp_project_id, type: :string, required: true, desc: 'PhraseApp project ID.'
+  method_option :parent_commit,        type: :string, required: true, desc: 'git commit hash of locales being uploaded'
+  def update_parent_commit
+    handle_errors do
+      updater = PhraseAppUpdater.new(
+        options[:phraseapp_api_key],
+        options[:phraseapp_project_id],
+        options[:file_format])
+
+      updater.update_parent_commit(options[:parent_commit])
+    end
+  end
+
+  desc 'diff <path1> <path2>',
+       'Compare locale file directories <path1> and <path2>'
+
+  long_desc <<-LONGDESC
+    Perform a JSON diff of locale files in path1 and path2.
+    Exits with 1 if there were differences, or 0 if no differences"
+  LONGDESC
+
+  method_option :quiet, type: :boolean, default: false, desc: 'Suppress output'
+
+  def diff(path1, path2)
+    validate_readable_path!('path1', path1)
+    validate_readable_path!('path2', path2)
+
+    handle_errors do
+      updater = PhraseAppUpdater.new(nil, nil, options[:file_format])
+      diffs = updater.diff_directories(path1, path2)
+      if diffs.empty?
+        exit(0)
+      else
+        print_diff(diffs) unless options[:quiet]
+        exit(1)
       end
-    rescue PhraseAppUpdater::PhraseAppAPI::BadAPIKeyError => e
-      puts "Bad PhraseApp API key."
-    rescue PhraseAppUpdater::PhraseAppAPI::BadProjectIDError => e
-      puts "Bad PhraseApp project ID: #{phraseapp_project_id}"
-    rescue PhraseAppUpdater::LocaleFile::BadFileTypeError => e
-      puts "Bad filetype for localization files: #{e.message}"
-    rescue StandardError => e
-      puts "Unknown error when pushing files."
-      raise e
     end
   end
 
+  desc 'merge <ancestor_path> <our_path> <their_path>',
+       '3-way merge locale file directories <ancestor_path>, <our_path>, <their_path> into TO.'
 
-  desc "pull", "Pulls data from PhraseApp for deployment, replacing missing keys from fallback."
-  option :fallback_path,         type: :string,  required: true, desc: "Path to the files to restore missing keys from."
-  option :destination_path,      type: :string,                  desc: "Path to write the resolved files to. If not provided, --fallback_path is used."
-  option :phraseapp_api_key,     type: :string,                  desc: "PhraseApp API key. Shell variable: PA_API_KEY"
-  option :phraseapp_project_id,  type: :string,                  desc: "PhraseApp project ID. Shell variable: PA_PROJECT_ID"
-  option :config_file_path,      type: :string,                  desc: "Path to .phraseapp.yml config file to read API key and project ID."
-  option :file_format,           type: :string,                  desc: "Filetype of localization files."
-
-  def pull
-    phraseapp_api_key, phraseapp_project_id, file_format = load_phraseapp_configuration(options)
-
-    fallback_path = options[:fallback_path]
-    validate_readable_path!('fallback_path', fallback_path)
-
-    destination_path = options.fetch(:destination_path, fallback_path).to_s
-    validate_writable_path!('destination_path', destination_path)
-
-    begin
-      files = PhraseAppUpdater.new(phraseapp_api_key, phraseapp_project_id, file_format).pull(fallback_path)
-      write_locale_files(destination_path, files)
-    rescue PhraseAppUpdater::PhraseAppAPI::BadAPIKeyError => e
-      puts "Bad PhraseApp API key."
-    rescue PhraseAppUpdater::PhraseAppAPI::BadProjectIDError => e
-      puts "Bad PhraseApp project ID: #{phraseapp_project_id}"
-    rescue PhraseAppUpdater::LocaleFile::BadFileTypeError => e
-      puts "Bad filetype for localization files: #{e.message}"
-    rescue StandardError => e
-      puts "Unknown error when pulling files"
-      raise e
+  long_desc <<-LONGDESC
+    Perform a JSON-aware 3-way merge of locale files in directories <ancestor_path>, <our_path>, <their_path> into TO.
+
+    The merge resolution strategy always selects `ours` in the case of a conflict.
+  LONGDESC
+
+  method_option :to, type: :string, required: true, desc: 'Target directory'
+
+  def merge(ancestor_path, our_path, their_path)
+    validate_readable_path!('ancestor_path', ancestor_path)
+    validate_readable_path!('our_path', our_path)
+    validate_readable_path!('their_path', their_path)
+
+    result_path = options[:to]
+    validate_writable_path!('to', result_path)
+
+    handle_errors do
+      updater = PhraseAppUpdater.new(nil, nil, options[:file_format])
+      updater.merge_directories(our_path, their_path, ancestor_path, result_path)
     end
   end
 
-  desc "default", "Prints gem information"
+  desc 'merge_file <ancestor> <ours> <theirs>',
+       'Perform 3-way merge of a single file into TO'
+
+  long_desc <<-LONGDESC
+    Perform 3-way merge of a single file into TO
+
+    Intended for use as a git merge-driver with:
+      [merge "phraseapp-locale"]
+        name = PhraseApp locale file merge driver
+        driver = phraseapp_updater merge_file %O %A %B --to %P
+  LONGDESC
+
+  method_option :to, type: :string, required: true, desc: 'Target file'
+
+  def merge_file(ancestor, ours, theirs)
+    validate_readable_file!('ancestor', ancestor)
+    validate_readable_file!('ours', ours)
+    validate_readable_file!('theirs', theirs)
+    validate_writable_file!('to', to)
+
+    # Git provides an empty file when there is no common ancestor in the
+    # merge-base. Because we want to merge from an empty hash structure instead,
+    # pass `nil` to `merge_files`.
+    ancestor = nil if File.zero?(ancestor)
+
+    updater = PhraseAppUpdater.new(nil, nil, file_format)
+    updater.merge_files(ours, theirs, ancestor, to)
+  end
+
+  desc 'default', 'Prints gem information'
   option :version, aliases: [:v]
 
   def default
@@ -98,37 +211,54 @@ class PhraseAppUpdaterCLI < Thor
 
   private
 
-  def load_phraseapp_configuration(options)
-    if options[:config_file_path]
-
-      if [:phraseapp_api_key, :phraseapp_project_id, :file_format].any? { |option| options.has_key?(:option) }
-        raise RuntimeError.new("Provided both a path to PhraseApp config file and command line arguments. Specify only one. #{options}")
+  def print_diff(diffs)
+    normalized_diffs = diffs.flat_map do |diff|
+      type, path, c1, c2 = diff
+      if type == '~'
+        [['-', path, c1], ['+', path, c2]]
+      else
+        [diff]
       end
-
-      config = PhraseAppUpdater.load_config(options[:config_file_path])
-
-      phraseapp_api_key    = config.api_key
-      phraseapp_project_id = config.project_id
-      file_format          = config.file_format
-    else
-      phraseapp_api_key    = options.fetch(:phraseapp_api_key, ENV["PA_API_KEY"]).to_s
-      phraseapp_project_id = options.fetch(:phraseapp_project_id, ENV["PA_PROJECT_ID"]).to_s
-      file_format          = options.fetch(:file_format, ENV["PA_FILE_FORMAT"]).to_s
     end
 
-    if phraseapp_api_key.empty?
-      raise RuntimeError.new("Must provide Phraseapp API key. --phraseapp_api_key or PA_API_KEY")
+    normalized_diffs.each do |type, path, change|
+      puts "#{type} #{path}: #{change}"
     end
+  end
 
-    if phraseapp_project_id.empty?
-      raise RuntimeError.new("Must provide Phraseapp project ID. --phraseapp_project_id or PA_PROJECT_ID")
-    end
+  def handle_errors
+    yield
+  rescue PhraseAppUpdater::PhraseAppAPI::BadAPIKeyError
+    STDERR.puts 'Bad PhraseApp API key.'
+    exit(1)
+  rescue PhraseAppUpdater::PhraseAppAPI::BadProjectIDError => e
+    STDERR.puts "Bad PhraseApp project ID: #{e.project_id}"
+    exit(1)
+  rescue PhraseAppUpdater::PhraseAppAPI::ProjectNameTakenError
+    STDERR.puts "PhraseApp project name already taken: #{options[:phraseapp_project_name]}"
+    exit(1)
+  rescue PhraseAppUpdater::LocaleFile::BadFileTypeError => e
+    STDERR.puts "Bad filetype for localization files: #{e.message}"
+    exit(1)
+  rescue PhraseAppUpdater::PhraseAppAPI::MissingGitParentError
+    STDERR.puts 'Git ancestor commit not recorded on PhraseApp project'
+    exit(1)
+  rescue StandardError => e
+    STDERR.puts "Unknown error occurred: #{e.message}"
+    STDERR.puts e.backtrace
+    exit(1)
+  end
 
-    if file_format.empty?
-      raise RuntimeError.new("Must provide file format for Phraseapp project. --file_format or PA_FILE_FORMAT")
+  def validate_readable_file!(name, file)
+    unless File.readable?(file) && File.file?(file)
+      raise RuntimeError.new("#{name} is not a readable file: #{file}")
     end
+  end
 
-    return [phraseapp_api_key, phraseapp_project_id, file_format]
+  def validate_writable_file!(name, file)
+    unless File.writable?(file) && File.file?(file)
+      raise RuntimeError.new("#{name} is not a writable file: #{file}")
+    end
   end
 
   def validate_path!(name, path)
@@ -153,14 +283,11 @@ class PhraseAppUpdaterCLI < Thor
     end
   end
 
-  def write_locale_files(path, files)
-    files.each do |file|
-      full_path = "#{path.chomp('/')}/#{file.name_with_extension}"
-      File.write(full_path, file.content)
+  def sh(x)
+    `#{x}`.tap do
+      raise RuntimeError.new("Shell command failed: '#{x}'") unless $?.success?
     end
-    puts "Wrote #{files.count} files to #{path}: #{files.map(&:name_with_extension)}"
   end
 end
 
 PhraseAppUpdaterCLI.start(ARGV)
-