hg convert --authors wrongUsers <-- what is the format of the file?

Question

Related here. Instructions here guide with example:

john=John Smith <[email protected]>
tom=Tom Johnson <[email protected]>

but what does it mean? Suppose I want to replace "hh <[email protected]>" with "hhh <[email protected]>", what would that line look like? What do the terms username, mapping and filename mean? I can find this part "username mapping filename" from "convert/__init__.py":

cmdtable = {
    "convert":
        (convert,
         [('A', 'authors', '', _('username mapping filename')),
          ('d', 'dest-type', '', _('destination repository type')),
          ('', 'filemap', '', _('remap file names using contents of file')),
          ('r', 'rev', '', _('import up to target revision REV')),

It makes an object where the authors are stored as dict, convcmd.py line 79:

class converter(object):
    def __init__(self, ui, source, dest, revmapfile, opts):

        self.source = source
        self.dest = dest
        self.ui = ui
        self.opts = opts
        self.commitcache = {}
        self.authors = {}
        self.authorfile = None

it splits the each line in authorfile with "=" but from this onwards I am lost how does it work. So what is the authors.file to fix wrong authors supposingly meant to look like? If you can, please point me to the source line because I find the docs very unreadable.

[Update]

I have tried all kind of options for the file but the "$ hg status"/"$ hg log --template '{author}\n'" won't get changed. Either I need to do something odd after the command "$ hg convert --authors conversionAuthors ." or I cannot match the authors. How can I know "exact match"? How can I know whether I succeed?

Answer 1

The convert extension uses a literal text substitution.

A quick experiment shows if you want to replace hh <[email protected]>, you simply create an author map file with these contents:

hh <[email protected]> = hhh <[email protected]>

The left-hand side must be an exact match for the author you want to replace. If it is not an exact match, no substitution is performed.