def determine_new_tag(self):
    """Determines the next semver tag for the repository at the path.

    If the commit at HEAD is already tagged with a tag matching --tag_regex_str,
    this function is a no-op. Otherwise it determines the semantic version bump
    for the commits since the last tag matching 'version-X.Y.Z' and suggests a new tag
    based on the commit messages. This suggestion can be overridden with
    --next_tag, which will be used if there are any commits after the last
    semver tag matching 'version-X.Y.Z'.

    Returns:
      [VersionBump]: Next semantic version tag to be used, along with what type
      of version bump it was. Version tag is of the form 'version-X.Y.Z'.
    """
    if self.__next_tag:
      return VersionBump(self.__next_tag, self.get_head_commit())

    # 'git log' entries of the form '$hash $commit_title'
    log_onelines = run_quick('git -C {path} log --pretty=oneline'.format(path=self.path),
                             echo=False).stdout.strip().split('\n')
    commit_hashes = [line.split(' ')[0].strip() for line in log_onelines]

    # Full commit messages, including bodies for finding 'BREAKING CHANGE:'.
    msgs = [
      run_quick('git -C {path} log -n 1 --pretty=medium {hash}'.format(path=self.path, hash=h),
                echo=False).stdout.strip() for h in commit_hashes
    ]

    if len(commit_hashes) != len(msgs):
      raise IOError('Git commit hash list and commit message list are unequal sizes.')

    return self.bump_semver(self.__current_version, commit_hashes, msgs)

  def generate_changelog(self):
    """Generate a release changelog and write it to a file.

    The changelog contains a section per microservice that describes the
    changes made since the last Spinnaker release. It also contains the
    version information as well.
    """
    changelog = ['Spinnaker {0}\n'.format(self.__toplevel_version)]
    for comp, hash in self.__changelog_start_hashes.iteritems():
      version = self.__version_from_tag(comp)

      # Generate the changelog for the component.
      print 'Generating changelog for {comp}...'.format(comp=comp)
      # Assumes the remote repository is aliased as 'origin'.
      component_url = run_quick('git -C {path} config --get remote.origin.url'
                                .format(path=comp)).stdout.strip()
      if component_url.endswith('.git'):
        component_url = component_url.replace('.git', '')
      result = run_quick('cd {comp}; clog -r {url} -f {hash} --setversion {version}; cd ..'
                         .format(comp=comp, url=component_url, hash=hash, version=version))
      if result.returncode != 0:
        print "Changelog generation failed for {0} with \n{1}\n exiting...".format(comp, result.stdout)
        exit(result.returncode)
      # Capitalize
      comp_cap = comp[0].upper() + comp[1:]
      changelog.append('# {0}\n{1}'.format(comp_cap, result.stdout))
    print 'Writing changelog...'
    # Write the changelog with the toplevel version without the build number.
    # This is ok since the changelog is only published if the toplevel version is released.
    changelog_file = self.__changelog_output or '{0}-changelog.md'.format(self.__toplevel_version)
    with open(changelog_file, 'w') as clog:
      clog.write('\n'.join(changelog))

  def __tag_gcb_mirror(cls, name, mirror_base_url, gradle_root, sync_branch, logfile):
    add_mirror_cmds = [
      'git remote add mirror {base_url}/{name}.git'.format(base_url=mirror_base_url, name=name),
      'git fetch mirror'
    ]
    run_shell_and_log(add_mirror_cmds, logfile, cwd=gradle_root)

    all_remote_branches = run_quick('git -C {name} branch -r'.format(name=name),
                                    echo=False).stdout.strip().splitlines()
    checkout_cmd = ''
    print all_remote_branches
    if 'mirror/{}'.format(sync_branch) in all_remote_branches:
      checkout_cmd = 'git checkout mirror/{branch}'.format(branch=sync_branch)
    else:
      checkout_cmd = 'git checkout {branch}'.format(branch=sync_branch)

    tag = run_quick('cat {name}-gcb-trigger.yml'.format(name=name), echo=False).stdout.strip()
    cmds = [
      checkout_cmd,
      'git merge origin/{branch}'.format(branch=sync_branch),
      'git push mirror {branch}'.format(branch=sync_branch),
      'git push mirror {tag}'.format(name=name, tag=tag)
    ]
    if os.path.exists(logfile):
      os.remove(logfile)
    run_shell_and_log(cmds, logfile, cwd=gradle_root)
    return tag

  def delete_unwanted_tags(self):
    """Locally deletes tags that don't match TAG_MATCHER.

    This is so that gradle will use the latest resolved semantic version from
    our tag pattern when it builds the package.
    """
    print ('Deleting {0} unwanted git tags locally from {1}'
           .format(len(self.__tags_to_delete), self.path))
    for bad_hash_tag in self.__tags_to_delete:
      run_quick('git -C {path} tag -d {tag}'
                .format(path=self.path, tag=bad_hash_tag.tag), echo=False)

  def delete_unwanted_tags(self):
    """Locally deletes tags that don't match TAG_MATCHER.

    This is so that gradle will use the latest resolved semantic version from
    our tag pattern when it builds the package.
    """
    for bad_hash_tag in self.__tags_to_delete:
      # NOTE: The following command prints output to STDOUT, so we don't
      # explicitly log anything.
      run_quick('git -C {path} tag -d {tag}'
                .format(path=self.path, tag=bad_hash_tag.tag))

  def create_tarball(self):
    """Create a tar.gz file from the instance specified by the options.

    The file will be written to options.tarball_uri.
    It can be later turned into a GCE image by passing it as the --source-uri
    to gcloud images create.
    """
    project = self.__project
    basename = os.path.basename(self.options.tarball_uri).replace('_', '-')
    first_dot = basename.find('.')
    if first_dot:
        basename = basename[0:first_dot]
    disk_name = '{name}-export'.format(name=basename)
    print 'Attaching external disk "{disk}" to extract image tarball.'.format(
        disk=disk_name)

    # TODO(ewiseblatt): 20151002
    # Add an option to reuse an existing disk to reduce the cycle time.
    # Then guard the create/format/destroy around this option.
    # Still may want/need to attach/detach it here to reduce race conditions
    # on its use since it can only be bound to once instance at a time.
    check_run_quick('gcloud compute disks create '
                    ' {disk_name} --project {project} --zone {zone} --size=10'
                    .format(disk_name=disk_name,
                            project=self.__project,
                            zone=self.__zone),
                    echo=False)

    check_run_quick('gcloud compute instances attach-disk {instance}'
                    ' --disk={disk_name} --device-name=export-disk'
                    ' --project={project} --zone={zone}'
                    .format(instance=self.__instance,
                            disk_name=disk_name,
                            project=self.__project,
                            zone=self.__zone),
                    echo=False)
    try:
      self.__extract_image_tarball_helper()
    finally:
      print 'Detaching and deleting external disk.'
      run_quick('gcloud compute instances detach-disk -q {instance}'
                ' --disk={disk_name} --project={project} --zone={zone}'
                .format(instance=self.__instance,
                        disk_name=disk_name,
                        project=self.__project,
                        zone=self.__zone),
                echo=False)
      run_quick('gcloud compute disks delete -q {disk_name}'
                ' --project={project} --zone={zone}'
                .format(disk_name=disk_name,
                        project=self.__project,
                        zone=self.__zone),
                echo=False)

  def __is_ready(self):
    description = run_quick(
        'aws ec2 describe-instances'
        ' --profile {region}'
        ' --output json'
        ' --instance-ids {id}'
        ' --query "Reservations[*].Instances[*]"'
        .format(region=self.options.deploy_aws_region,
                id=self.__instance_id),
        echo=False)
    if description.returncode != 0:
      logging.warning('Could not determine public IP: %s', description)
      return False

    # result is an array of reservations of ararys of instances.
    # but we only expect one, so fish out the first instance info
    info = json.JSONDecoder().decode(description.stdout)[0][0]
    state = info.get('State', {}).get('Name')
    if state in ['pending', 'initializing']:
      logging.info('Waiting for %s to finish initializing (state=%s)',
                   self.__instance_id, state)
      return False

    if state in ['shutting-down', 'terminated']:
      raise ValueError('VM failed: {0}'.format(info))

    logging.info('%s is in state %s', self.__instance_id, state)
    self.set_instance_ip(info.get('PublicIpAddress'))
    # attempt to ssh into it so we know we're accepting connections when
    # we return. It takes time to start
    logging.info('Checking if it is ready for ssh...')
    check = run_quick(
        'ssh'
        ' -i {ssh_key}'
        ' -o StrictHostKeyChecking=no'
        ' -o UserKnownHostsFile=/dev/null'
        ' {user}@{ip}'
        ' "exit 0"'
        .format(user=self.hal_user,
                ip=self.instance_ip,
                ssh_key=self.ssh_key_path),
        echo=False)
    if check.returncode == 0:
      logging.info('READY')
      return True

    # Sometimes ssh accepts but authentication still fails
    # for a while. If this is the case, then try again
    # though the whole loop to distinguish VM going away.
    logging.info('%s\nNot yet ready...', check.stdout.strip())
    return False

  def cleanup_instance(self):
    """If we deployed an instance, tear it down."""
    if self.options.instance:
      print 'Leaving pre-existing instance {name}'.format(
          self.options.instance)
      return

    print 'Deleting instance {name}'.format(name=self.__instance)
    run_quick('gcloud compute instances delete {name}'
              '  --zone={zone} --project={project}'
              .format(name=self.__instance,
                      zone=self.__zone,
                      project=self.__project),
              echo=False)

def make_remote_directories(options):
    all = []
    if options.copy_personal_files:
        all.append('.gradle')
    if options.aws_credentials:
        all.append('.aws')
    if options.master_yml:
        all.append('.spinnaker')
    if options.copy_gcloud_config:
        all.append('.config/gcloud')

    if all:
        command = ' '.join([
            'gcloud compute ssh',
            options.instance,
            '--project', get_project(options),
            '--zone', get_zone(options),
            '--command=\'bash -c "for i in {0}; do mkdir -p \\$i; done"\''.format(' '.join(all))])

        while True:
            result = run_quick(command, echo=False)
            if not result.returncode:
                break
            print 'New instance does not seem ready yet...retry in 5s.'
            time.sleep(5)

def copy_file(options, source, target):
    if os.path.exists(source):
        # TODO(ewiseblatt): we can use scp here instead, and pass the
        # credentials we want to copy with rather than the additional command
        # below. But we need to figure out the IP address to copy to.
        # For now, do it the long way.
        print 'Copying {source}'.format(source=source)
        command = ' '.join([
            'gcloud compute copy-files',
            '--project', get_project(options),
            '--zone', options.zone,
            source,
            '{instance}:{target}'.format(instance=options.instance,
                                         target=target)])
        while True:
            result = run_quick(command, echo=False)
            if not result.returncode:
                break
            print 'New instance does not seem ready yet...retry in 5s.'
            time.sleep(5)

        command = ' '.join([
            'gcloud compute ssh',
            '--command="chmod 600 /home/{gcp_user}/{target}"'.format(
                gcp_user=os.environ['LOGNAME'], target=target),
            options.instance,
            '--project', get_project(options),
            '--zone', options.zone])
        check_run_quick(command, echo=False)

  def maybe_generate_clean_user_local():
    """Generate a spinnaker-local.yml file without environment variables refs"""
    user_dir = DevInstallationParameters.USER_CONFIG_DIR
    user_config_path = os.path.join(user_dir, 'spinnaker-local.yml')
    if os.path.exists(user_config_path):
      return
    if not os.path.exists(user_dir):
      os.mkdir(user_dir)

    with open('{config_dir}/default-spinnaker-local.yml'.format(
                  config_dir=DevInstallationParameters.INSTALLED_CONFIG_DIR),
              'r') as f:
      content = f.read()

    content = populate_aws_yml(content)
    content = populate_google_yml(content)

    with open(user_config_path, 'w') as f:
      f.write(content)
    os.chmod(user_config_path, 0600)

    change_path = os.path.join(os.path.dirname(os.path.dirname(__file__)),
                               'install', 'change_cassandra.sh')
    got = run_quick(change_path
                    + ' --echo=inMemory --front50=gcs'
                    + ' --change_defaults=false --change_local=true',
                    echo=False)

  def validate_options_helper(cls, options):
    """Adds custom configuration parameters to argument parser.

    This is a helper function for make_deployer().
    """
    if not options.deploy_google_project:
      raise ValueError('--deploy_google_project not specified.')
    if not options.deploy_google_instance:
      raise ValueError('--deploy_google_instance not specified.')
    if not options.deploy_hal_google_service_account:
      raise ValueError('--deploy_hal_google_service_account not specified.')

    if options.deploy_deploy:
      response = run_quick(
          'gcloud compute instances describe'
          ' --account {gcloud_account}'
          ' --project {project} --zone {zone} {instance}'
          .format(gcloud_account=options.deploy_hal_google_service_account,
                  project=options.deploy_google_project,
                  zone=options.deploy_google_zone,
                  instance=options.deploy_google_instance),
          echo=False)

      if response.returncode == 0:
        raise ValueError(
            '"{instance}" already exists in project={project} zone={zone}'
            .format(instance=options.deploy_google_instance,
                    project=options.deploy_google_project,
                    zone=options.deploy_google_zone))

 def get_head_commit(self):
   """Retrieves the head commit hash.
   """
   head_commit_res = run_quick('git -C {path} rev-parse HEAD'
                               .format(path=self.path),
                               echo=False)
   return head_commit_res.stdout.strip()

  def __tag_head_with_build(self, version_bump_tag):
    """Tags the current branch's HEAD with the next semver gradle build tag.

    Args:
      version_bump_tag [String]: Semver string to add as a gradle build tag.
    """
    next_tag_with_build = '{0}-{1}'.format(version_bump_tag,
                                           self.build_number)
    # This tag is for gradle to use as the package version. It incorporates the
    # build number for uniqueness when publishing. This tag is of the form
    # 'X.Y.Z-$build_number' for gradle to use correctly. This is not pushed
    # to the upstream git repository.
    first_dash_idx = next_tag_with_build.index('-')
    gradle_version = next_tag_with_build[first_dash_idx + 1:]
    run_quick('git -C {path} tag {next_tag} HEAD'
              .format(path=self.path, next_tag=gradle_version))

def check_s3_path(path):
  check_result = run_quick('aws --version', echo=False)
  if check_result.returncode:
    error = """
ERROR: aws is required to retrieve the spinnaker release from S3.
       If you already have aws, fix your path.
       Otherwise install awscli with "sudo apt-get install awscli".
       Then run again.
"""
    raise RuntimeError(error)

  result = run_quick('aws s3 ls ' + path, echo=False)
  if result.returncode:
      error = ('The path "{dir}" does not seem to exist within S3.'
               ' aws s3 ls returned "{stdout}"\n'.format(
                    dir=path,  stdout=result.stdout.strip()))
      raise RuntimeError(error)

def ensure_gcs_bucket(name, project=''):
  """Ensure that the desired GCS bucket exists, creating it if needed.

  Args:
    name [string]: The bucket name.
    project [string]: Optional Google Project id that will own the bucket.
      If none is provided, then the bucket will be associated with the default
      bucket configured to gcloud.

  Raises:
    RutimeError if the bucket could not be created.
  """
  bucket = 'gs://'+ name
  if not project:
      config_result = run_quick('gcloud config list', echo=False)
      error = None
      if config_result.returncode:
        error = 'Could not run gcloud: {error}'.format(
            error=config_result.stdout)
      else:
        match = re.search('(?m)^project = (.*)', config_result.stdout)
        if not match:
          error = ('gcloud is not configured with a default project.\n'
                   'run gcloud config or provide a --google_project.\n')
      if error:
        raise SystemError(error)

      project = match.group(1)

  list_result = run_quick('gsutil list -p ' +  project, echo=False)
  if list_result.returncode:
    error = ('Could not create Google Cloud Storage bucket'
             '"{name}" in project "{project}":\n{error}'
             .format(name=name, project=project, error=list_result.stdout))
    raise RuntimeError(error)

  if re.search('(?m)^{bucket}/\n'.format(bucket=bucket), list_result.stdout):
    sys.stderr.write(
        'WARNING: "{bucket}" already exists. Overwriting.\n'.format(
        bucket=bucket))
  else:
    print 'Creating GCS bucket "{bucket}" in project "{project}".'.format(
        bucket=bucket, project=project)
    check_run_quick('gsutil mb -p {project} {bucket}'
                    .format(project=project, bucket=bucket),
                    echo=True)

def check_gcloud():
    result = run_quick('gcloud --version', echo=False)
    if not result.returncode:
        return

    sys.stderr.write('ERROR: This program requires gcloud. To obtain gcloud:\n'
                     '       curl https://sdk.cloud.google.com | bash\n')
    sys.exit(-1)

 def __hal_upload_profile(self, component, bom_file, profile_path):
   result = run_quick(
     'hal admin publish profile {0} --color false --bom-path {1} --profile-path {2}'
     .format(component, bom_file, profile_path)
   )
   if result.returncode != 0:
     print "'hal admin publish profile' command failed with: \n{0}\nexiting...".format(result.stdout)
     exit(result.returncode)

 def unpack_bom(self):
   """Load the release candidate BOM into memory.
   """
   bom_yaml_string = run_quick('hal versions bom {0} --color false'
                               .format(self.__rc_version), echo=False).stdout.strip()
   print bom_yaml_string
   self.__bom_dict = yaml.load(bom_yaml_string)
   print self.__bom_dict

 def unpack_bom(self):
   """Load the release candidate BOM into memory.
   """
   bom_yaml_string = run_quick('hal version bom {0} --color false --quiet'
                               .format(self.__rc_version), echo=False).stdout.strip()
   print 'bom yaml string pulled by hal: \n\n{0}\n\n'.format(bom_yaml_string)
   self.__bom_dict = yaml.load(bom_yaml_string)
   print self.__bom_dict