def retrieve
      raise RetrieverError.new("retriever is unavailable") unless available?
      updated = false
      explanation = ''
      if exists?
        @logger.operation(:updating) do
          # a retriever may be able to determine that the repo directory is
          # already pointing to the same commit as the revision. in that case
          # we can return quickly.
          if remote_differs?
            # there is no point in updating and failing the size check when the
            # directory on disk already exceeds size limit; fall back to a clean
            # checkout in hopes that the latest revision corrects the issue.
            if size_limit_exceeded?
              explanation = 'switching to checkout due to existing directory exceeding size limimt'
            else
              # attempt update.
              begin
                do_update
                updated = true
              rescue ::RightScraper::Processes::Shell::LimitError
                # update exceeded a limitation; requires user intervention
                raise
              rescue Exception => e
                # retry with clean checkout after discarding repo dir.
                explanation = 'switching to checkout after unsuccessful update'
              end
            end
          else
            # no retrieval needed but warn exactly why we didn't do full
            # checkout to avoid being challenged about it.
            repo_ref = @repository.tag
            do_update_tag
            full_head_ref = @repository.tag
            abbreviated_head_ref = full_head_ref[0..6]
            if repo_ref == full_head_ref || repo_ref == abbreviated_head_ref
              detail = abbreviated_head_ref
            else
              detail = "#{repo_ref} = #{abbreviated_head_ref}"
            end
            message =
              "Skipped updating local directory due to the HEAD commit SHA " +
              "on local matching the remote repository reference (#{detail})."
            @logger.note_warning(message)
            return false
          end
        end
      end

      # Clean checkout only if not updated.
      unless updated
        @logger.operation(:checkout, explanation) do
          # remove any full or partial directory before attempting a clean
          # checkout in case repo_dir is in a bad state.
          if exists?
            ::FileUtils.remove_entry_secure(@repo_dir)
          end
          ::FileUtils.mkdir_p(@repo_dir)
          begin
            do_checkout
          rescue Exception
            # clean checkout failed; repo directory is in an undetermined
            # state and must be deleted to prevent a future update attempt.
            if exists?
              ::FileUtils.remove_entry_secure(@repo_dir) rescue nil
            end
            raise
          end
        end
      end
      true
    end
def retrieve
      raise RetrieverError.new("retriever is unavailable") unless available?
      updated = false
      explanation = ''
      if exists?
        @logger.operation(:updating) do
          # a retriever may be able to determine that the repo directory is
          # already pointing to the same commit as the revision. in that case
          # we can return quickly.
          if remote_differs?
            # there is no point in updating and failing the size check when the
            # directory on disk already exceeds size limit; fall back to a clean
            # checkout in hopes that the latest revision corrects the issue.
            if size_limit_exceeded?
              explanation = 'switching to checkout due to existing directory exceeding size limimt'
            else
              # attempt update.
              begin
                do_update
                updated = true
              rescue ::RightScraper::Processes::Shell::LimitError
                # update exceeded a limitation; requires user intervention
                raise
              rescue Exception => e
                # retry with clean checkout after discarding repo dir.
                explanation = 'switching to checkout after unsuccessful update'
              end
            end
          else
            # no retrieval needed but warn exactly why we didn't do full
            # checkout to avoid being challenged about it.
            repo_ref = @repository.tag
            do_update_tag
            full_head_ref = @repository.tag
            abbreviated_head_ref = full_head_ref[0..6]
            if repo_ref == full_head_ref || repo_ref == abbreviated_head_ref
              detail = abbreviated_head_ref
            else
              detail = "#{repo_ref} = #{abbreviated_head_ref}"
            end
            message =
              "Skipped updating local directory due to the HEAD commit SHA " +
              "on local matching the remote repository reference (#{detail})."
            @logger.note_warning(message)
            return false
          end
        end
      end

      # Clean checkout only if not updated.
      unless updated
        @logger.operation(:checkout, explanation) do
          # remove any full or partial directory before attempting a clean
          # checkout in case repo_dir is in a bad state.
          if exists?
            ::FileUtils.remove_entry_secure(@repo_dir)
          end
          ::FileUtils.mkdir_p(@repo_dir)
          begin
            do_checkout
          rescue Exception
            # clean checkout failed; repo directory is in an undetermined
            # state and must be deleted to prevent a future update attempt.
            if exists?
              ::FileUtils.remove_entry_secure(@repo_dir) rescue nil
            end
            raise
          end
        end
      end
      true
    end
Attempts to update and then resorts to clean checkout for repository.