def get_format_version():
     """Return the integer format version number, or None if the
     branch doesn't have any StGit metadata at all, of any version."""
     fv = config.get(key)
     ofv = config.get(old_key)
     if fv:
         # Great, there's an explicitly recorded format version
         # number, which means that the branch is initialized and
         # of that exact version.
         return int(fv)
     elif ofv:
         # Old name for the version info: upgrade it.
         config.set(key, ofv)
         config.unset(old_key)
         return int(ofv)
     elif os.path.isdir(os.path.join(branch_dir, 'patches')):
         # There's a .git/patches/<branch>/patches dirctory, which
         # means this is an initialized version 1 branch.
         return 1
     elif os.path.isdir(branch_dir):
         # There's a .git/patches/<branch> directory, which means
         # this is an initialized version 0 branch.
         return 0
     else:
         # The branch doesn't seem to be initialized at all.
         return None

    def clone(self, target_series):
        """Clones a series
        """
        try:
            # allow cloning of branches not under StGIT control
            base = self.get_base()
        except:
            base = git.get_head()
        Series(target_series).init(create_at=base)
        new_series = Series(target_series)

        # generate an artificial description file
        new_series.set_description('clone of "%s"' % self.get_name())

        # clone self's entire series as unapplied patches
        try:
            # allow cloning of branches not under StGIT control
            applied = self.get_applied()
            unapplied = self.get_unapplied()
            patches = applied + unapplied
            patches.reverse()
        except:
            patches = applied = unapplied = []
        for p in patches:
            patch = self.get_patch(p)
            newpatch = new_series.new_patch(
                p,
                message=patch.get_description(),
                can_edit=False,
                unapplied=True,
                bottom=patch.get_bottom(),
                top=patch.get_top(),
                author_name=patch.get_authname(),
                author_email=patch.get_authemail(),
                author_date=patch.get_authdate(),
            )
            if patch.get_log():
                out.info("Setting log to %s" % patch.get_log())
                newpatch.set_log(patch.get_log())
            else:
                out.info("No log for %s" % p)

        # fast forward the cloned series to self's top
        new_series.forward_patches(applied)

        # Clone parent informations
        value = config.get("branch.%s.remote" % self.get_name())
        if value:
            config.set("branch.%s.remote" % target_series, value)

        value = config.get("branch.%s.merge" % self.get_name())
        if value:
            config.set("branch.%s.merge" % target_series, value)

        value = config.get("branch.%s.stgit.parentbranch" % self.get_name())
        if value:
            config.set("branch.%s.stgit.parentbranch" % target_series, value)

def user():
    """Return the user information.
    """
    global __user
    if not __user:
        name=config.get('user.name')
        email=config.get('user.email')
        __user = Person(name, email)
    return __user;

def get_editor():
    for editor in [os.environ.get('GIT_EDITOR'),
                   config.get('stgit.editor'), # legacy
                   config.get('core.editor'),
                   os.environ.get('VISUAL'),
                   os.environ.get('EDITOR'),
                   'vi']:
        if editor:
            return editor

def get_editor():
    for editor in [
        os.environ.get("GIT_EDITOR"),
        config.get("stgit.editor"),  # legacy
        config.get("core.editor"),
        os.environ.get("VISUAL"),
        os.environ.get("EDITOR"),
        "vi",
    ]:
        if editor:
            return editor

def pull(repository = 'origin', refspec = None):
    """Fetches changes from the remote repository, using 'git pull'
    by default.
    """
    # we update the HEAD
    __clear_head_cache()

    args = [repository]
    if refspec:
        args.append(refspec)

    command = config.get('branch.%s.stgit.pullcmd' % get_head_file()) or \
              config.get('stgit.pullcmd')
    Run(*(command.split() + args)).run()

def pull(repository = 'origin', refspec = None):
    """Fetches changes from the remote repository, using 'git-pull'
    by default.
    """
    # we update the HEAD
    __clear_head_cache()

    args = [repository]
    if refspec:
        args.append(refspec)

    command = config.get('branch.%s.stgit.pullcmd' % get_head_file()) or \
              config.get('stgit.pullcmd')
    if __run(command, args) != 0:
        raise GitException, 'Failed "%s %s"' % (command, repository)

def __build_address_headers(msg, options, extra_cc = []):
    """Build the address headers and check existing headers in the
    template.
    """
    to_addr = ''
    cc_addr = ''
    extra_cc_addr = ''
    bcc_addr = ''

    autobcc = config.get('stgit.autobcc') or ''

    if options.to:
        to_addr = ', '.join(options.to)
    if options.cc:
        cc_addr = ', '.join(options.cc)
    if extra_cc:
        extra_cc_addr = ', '.join(extra_cc)
    if options.bcc:
        bcc_addr = ', '.join(options.bcc + [autobcc])
    elif autobcc:
        bcc_addr = autobcc

    # if an address is on a header, ignore it from the rest
    from_set = __update_header(msg, 'From')
    to_set = __update_header(msg, 'To', to_addr)
    # --auto generated addresses, don't include the sender
    __update_header(msg, 'Cc', extra_cc_addr, from_set)
    cc_set = __update_header(msg, 'Cc', cc_addr, to_set)
    bcc_set = __update_header(msg, 'Bcc', bcc_addr, to_set.union(cc_set))

def update_commit_data(cd, options):
    """Return a new CommitData object updated according to the command line
    options."""
    # Set the commit message from commandline.
    if options.message is not None:
        cd = cd.set_message(options.message)

    # Modify author data.
    cd = cd.set_author(options.author(cd.author))

    # Add Signed-off-by: or similar.
    if options.sign_str != None:
        sign_str = options.sign_str
    else:
        sign_str = config.get("stgit.autosign")
    if sign_str != None:
        cd = cd.set_message(
            add_sign_line(cd.message, sign_str,
                          cd.committer.name, cd.committer.email))

    # Let user edit the commit message manually, unless
    # --save-template or --message was specified.
    if not getattr(options, 'save_template', None) and options.message is None:
        cd = cd.set_message(edit_string(cd.message, '.stgit-new.txt'))

    return cd

def __build_address_headers(msg, options, extra_cc = []):
    """Build the address headers and check existing headers in the
    template.
    """
    def __replace_header(header, addr):
        if addr:
            crt_addr = msg[header]
            del msg[header]

            if crt_addr:
                msg[header] = address_or_alias(', '.join([crt_addr, addr]))
            else:
                msg[header] = address_or_alias(addr)

    to_addr = ''
    cc_addr = ''
    bcc_addr = ''

    autobcc = config.get('stgit.autobcc') or ''

    if options.to:
        to_addr = ', '.join(options.to)
    if options.cc:
        cc_addr = ', '.join(options.cc + extra_cc)
    elif extra_cc:
        cc_addr = ', '.join(extra_cc)
    if options.bcc:
        bcc_addr = ', '.join(options.bcc + [autobcc])
    elif autobcc:
        bcc_addr = autobcc

    __replace_header('To', to_addr)
    __replace_header('Cc', cc_addr)
    __replace_header('Bcc', bcc_addr)

def __build_cover(tmpl, msg_id, options, patches):
    """Build the cover message (series description) to be sent via SMTP
    """
    sender = __get_sender()

    if options.version:
        version_str = '%s' % options.version
        version_space = ' '
    else:
        version_str = ''
        version_space = ''

    if options.prefix:
        prefix_str = options.prefix
    else:
        prefix_str = config.get('stgit.mail.prefix')
    if prefix_str:
        prefix_space = ' '
    else:
        prefix_str = ''
        prefix_space = ''

    total_nr_str = str(len(patches))
    patch_nr_str = '0'.zfill(len(total_nr_str))
    if len(patches) > 1:
        number_str = '%s/%s' % (patch_nr_str, total_nr_str)
        number_space = ' '
    else:
        number_str = ''
        number_space = ''

    tmpl_dict = {'sender':       sender,
                 # for backward template compatibility
                 'maintainer':   sender,
                 # for backward template compatibility
                 'endofheaders': '',
                 # for backward template compatibility
                 'date':         '',
                 'version':      version_str,
                 'vspace':       version_space,
                 'prefix':       prefix_str,
                 'pspace':       prefix_space,
                 'patchnr':      patch_nr_str,
                 'totalnr':      total_nr_str,
                 'number':       number_str,
                 'nspace':       number_space,
                 'snumber':      number_str.strip(),
                 'shortlog':     stack.shortlog(crt_series.get_patch(p)
                                                for p in reversed(patches)),
                 'diffstat':     gitlib.diffstat(git.diff(
                     rev1 = git_id(crt_series, '%s^' % patches[0]),
                     rev2 = git_id(crt_series, '%s' % patches[-1]),
                     diff_flags = options.diff_flags))}

    try:
        msg_string = tmpl % tmpl_dict
    except KeyError, err:
        raise CmdException, 'Unknown patch template variable: %s' \
              % err

def interactive_merge(filename):
    """Run the interactive merger on the given file. Note that the
    index should not have any conflicts.
    """
    extensions = file_extensions()

    ancestor = filename + extensions['ancestor']
    current = filename + extensions['current']
    patched = filename + extensions['patched']

    if os.path.isfile(ancestor):
        three_way = True
        files_dict = {'branch1': current,
                      'ancestor': ancestor,
                      'branch2': patched,
                      'output': filename}
        imerger = config.get('stgit.i3merge')
    else:
        three_way = False
        files_dict = {'branch1': current,
                      'branch2': patched,
                      'output': filename}
        imerger = config.get('stgit.i2merge')

    if not imerger:
        raise GitMergeException, 'No interactive merge command configured'

    # check whether we have all the files for the merge
    for fn in [filename, current, patched]:
        if not os.path.isfile(fn):
            raise GitMergeException, \
                  'Cannot run the interactive merge: "%s" missing' % fn

    mtime = os.path.getmtime(filename)

    out.info('Trying the interactive %s merge'
             % (three_way and 'three-way' or 'two-way'))

    err = os.system(imerger % files_dict)
    if err != 0:
        raise GitMergeException, 'The interactive merge failed: %d' % err
    if not os.path.isfile(filename):
        raise GitMergeException, 'The "%s" file is missing' % filename
    if mtime == os.path.getmtime(filename):
        raise GitMergeException, 'The "%s" file was not modified' % filename

def keep_option():
    return [
        opt(
            "-k",
            "--keep",
            action="store_true",
            short="Keep the local changes",
            default=config.get("stgit.autokeep") == "yes",
        )
    ]

 def __address_or_alias(addr):
     if not addr:
         return None
     if addr.find('@') >= 0:
         # it's an e-mail address
         return addr
     alias = config.get('mail.alias.'+addr)
     if alias:
         # it's an alias
         return alias
     raise CmdException, 'unknown e-mail alias: %s' % addr

def rebase(tree_id = None):
    """Rebase the current tree to the give tree_id. The tree_id
    argument may be something other than a GIT id if an external
    command is invoked.
    """
    command = config.get('branch.%s.stgit.rebasecmd' % get_head_file()) \
                or config.get('stgit.rebasecmd')
    if tree_id:
        args = [tree_id]
    elif command:
        args = []
    else:
        raise GitException, 'Default rebasing requires a commit id'
    if command:
        # clear the HEAD cache as the custom rebase command will update it
        __clear_head_cache()
        Run(*(command.split() + args)).run()
    else:
        # default rebasing
        reset(tree_id = tree_id)

 def get_parent_branch(self):
     value = config.get("branch.%s.stgit.parentbranch" % self.get_name())
     if value:
         return value
     elif git.rev_parse("heads/origin"):
         out.note(
             ('No parent branch declared for stack "%s",' ' defaulting to "heads/origin".' % self.get_name()),
             ('Consider setting "branch.%s.stgit.parentbranch"' ' with "git config".' % self.get_name()),
         )
         return "heads/origin"
     else:
         raise StackException, 'Cannot find a parent branch for "%s"' % self.get_name()

 def get_parent_remote(self):
     value = config.get('branch.%s.remote' % self.get_name())
     if value:
         return value
     elif 'origin' in git.remotes_list():
         out.note(('No parent remote declared for stack "%s",'
                   ' defaulting to "origin".' % self.get_name()),
                  ('Consider setting "branch.%s.remote" and'
                   ' "branch.%s.merge" with "git config".'
                   % (self.get_name(), self.get_name())))
         return 'origin'
     else:
         raise StackException, 'Cannot find a parent remote for "%s"' % self.get_name()

def __set_smtp_credentials(options):
    """Set the (smtpuser, smtppassword, smtpusetls) credentials if the method
    of sending is SMTP.
    """
    global __smtp_credentials

    smtpserver = options.smtp_server or config.get('stgit.smtpserver')
    if options.mbox or options.git or smtpserver.startswith('/'):
        return

    smtppassword = options.smtp_password or config.get('stgit.smtppassword')
    smtpuser = options.smtp_user or config.get('stgit.smtpuser')
    smtpusetls = options.smtp_tls or config.get('stgit.smtptls') == 'yes'

    if (smtppassword and not smtpuser):
        raise CmdException('SMTP password supplied, username needed')
    if (smtpusetls and not smtpuser):
        raise CmdException('SMTP over TLS requested, username needed')
    if (smtpuser and not smtppassword):
        smtppassword = getpass.getpass("Please enter SMTP password: ")

    __smtp_credentials = (smtpuser, smtppassword, smtpusetls)

def diff_opts_option():
    def diff_opts_callback(option, opt_str, value, parser):
        if value:
            parser.values.diff_flags.extend(value.split())
        else:
            parser.values.diff_flags = []
    return [
        opt('-O', '--diff-opts', dest = 'diff_flags',
            default = (config.get('stgit.diff-opts') or '').split(),
            action = 'callback', callback = diff_opts_callback,
            type = 'string', metavar = 'OPTIONS',
            args = [strings('-M', '-C')],
            short = 'Extra options to pass to "git diff"')]

def address_or_alias(addr_pair):
    """Return a name-email tuple the e-mail address is valid or look up
    the aliases in the config files.
    """
    addr = addr_pair[1]
    if "@" in addr:
        # it's an e-mail address
        return addr_pair
    alias = config.get("mail.alias." + addr)
    if alias:
        # it's an alias
        return name_email(alias)
    raise CmdException, "unknown e-mail alias: %s" % addr