papers-cli 2.4__py3-none-any.whl → 2.6__py3-none-any.whl

papers/__main__.py

@@ -1,4 +1,4 @@
-"""That is the script called by papers
+"""That is the script called by the papers cli command
 """
 import os
 import sys
@@ -15,22 +15,41 @@ from papers import logger
 from papers.extract import extract_pdf_doi, isvaliddoi, extract_pdf_metadata
 from papers.extract import fetch_bibtex_by_doi
 from papers.encoding import parse_file, format_file, family_names, format_entries
-from papers.config import bcolors, Config, search_config, CONFIG_FILE, DATA_DIR, CONFIG_FILE_LEGACY
+from papers.config import bcolors, Config, search_config, CONFIG_FILE, CONFIG_FILE_LOCAL, DATA_DIR, CONFIG_FILE_LEGACY, BACKUP_DIR
 from papers.duplicate import list_duplicates, list_uniques, edit_entries
-from papers.bib import Biblio, FUZZY_RATIO, DEFAULT_SIMILARITY, entry_filecheck, backupfile, isvalidkey
+from papers.bib import Biblio, FUZZY_RATIO, DEFAULT_SIMILARITY, entry_filecheck, backupfile as backupfile_func, isvalidkey
+from papers.utils import move, checksum, ansi_link as link, view_pdf
 from papers import __version__
 
 
-def check_legacy_config(configfile):
-    " move config file from ~/.config/papersconfig.json to ~/.local/.share/papers/ "
-    if not os.path.exists(configfile) and os.path.exists(CONFIG_FILE_LEGACY):
-        os.makedirs(os.path.dirname(CONFIG_FILE), exist_ok=True)
+if os.path.exists(CONFIG_FILE_LEGACY):
+    # move config file from ~/.local/.share/papers/ to ~/.config/papersconfig.json .papers/config.json to .papersconfig.json"
+    if not os.path.exists(CONFIG_FILE):
+        logger.warning(f"Move legacy config file {CONFIG_FILE_LEGACY} to {CONFIG_FILE}'")
         shutil.move(CONFIG_FILE_LEGACY, CONFIG_FILE)
-        configfile = CONFIG_FILE
+    else:
+        logger.warning(f"Legacy config file found: {CONFIG_FILE_LEGACY}. Delete to remove this warning:  rm -f '{CONFIG_FILE_LEGACY}'")
+
+def check_legacy_config(configfile):
+    " move config file from ~/.local/.share/papers/ to ~/.config/papersconfig.json and .papers/config.json to .papersconfig.json"
+    if os.path.exists(configfile):
+        p = Path(configfile)
+        if configfile == CONFIG_FILE_LEGACY:
+            shutil.move(configfile, CONFIG_FILE)
+            configfile = CONFIG_FILE
+        elif p.name == "config.json" and p.parent.name == ".papers":
+            newname = str(p.parent.parent/CONFIG_FILE_LOCAL)
+            shutil.move(configfile, newname)
+            configfile = newname
+
     return configfile
 
 
 def get_biblio(config):
+    """
+    This function initializes a Biblio object based on the bibtex file specified as command line argument or in config file.
+    If no bibtex file is specified, it raises a ValueError().
+    """
     if config.bibtex is None:
         raise ValueError('bibtex is not initialized')
     relative_to = os.path.sep if config.absolute_paths else (os.path.dirname(config.bibtex) if config.bibtex else None)
@@ -44,91 +63,146 @@ def get_biblio(config):
 
 
 def _backup_bib(biblio, config, message=None):
+    if not config.git:
+        raise PapersExit('cannot backup without --git enabled')
     # backupdir = Path(config.file).parent
     backupdir = Path(config.gitdir)
     backupdir.mkdir(exist_ok=True)
-    backupfile = backupdir/'papers.bib'
 
     # remove if exists
-    backupfile.unlink(missing_ok=True)
+    config.backupfile.unlink(missing_ok=True)
+    config.backupfile_clean.unlink(missing_ok=True)
 
     ## Here we could create a copy of biblio since it is modified in place
     ## For now, we exit the program after saving, so don't bother
+    logger.debug(f'BACKUP: cp {config.bibtex} {config.backupfile}')
+    shutil.copy(config.bibtex, config.backupfile)
+    config.gitcmd(f"add {config.backupfile.name}")
+
     if config.backup_files:
         logger.info('backup bibliography with files')
         backupfilesdir = backupdir/"files"
         backupfilesdir.mkdir(exist_ok=True)
         biblio.filesdir = str(backupfilesdir)
-        biblio.rename_entries_files(copy=True, relative_to=backupdir)
-        biblio.save(backupfile)
-        config.gitcmd(f"add papers.bib")
+        biblio.rename_entries_files(copy=True, relative_to=backupdir, hardlink=True)
+        biblio.save(config.backupfile_clean)
+        config.gitcmd(f"add {config.backupfile_clean.name}")
         config.gitcmd(f"add files")
 
     else:
         logger.info('backup bibliography only (without files)')
         biblio.update_file_path(relative_to=backupdir)
-        biblio.save(backupfile)
-        config.gitcmd(f"add papers.bib", check=False)
+        biblio.save(config.backupfile_clean)
+        config.gitcmd(f"add {config.backupfile_clean.name}")
 
-    message = message or f'back-up {config.bibtex} after command:\n\n    papers ' +' '.join(sys.argv[1:])
+    message = message or f'papers ' +' '.join(sys.argv[1:])
     res = config.gitcmd(f"commit -m '{message}'", check=False)
-    config.gitcmd(f"clean -f")   # will also clean future files
+    # work on "main" branch for comitting (out of history branch)
+    config.gitcmd(f"checkout -B main")
+    config.gitcmd(f"clean -f")
+
+
+def _restore_from_backupdir(config, restore_files=False):
+    restore_cmd = f"papers add {config.backupfile_clean} --rename --copy" if config.backup_files else f"cp {config.backupfile} {config.bibtex}"
+    repair_message = f"papers backup broken :: cannot repair file links :: try to recover manually with `{restore_cmd}`"
+    try:
+        return _restore_from_backupdir_wrapped(config, restore_files=restore_files)
+    except Exception as error:
+        raise
+        logger.error(str(error))
+        raise PapersExit(repair_message)
+
+
+def _restore_from_backupdir_wrapped(config, restore_files=False):
+    # current = sp.check_output(f"git rev-parse --short HEAD", shell=True, cwd=config.gitdir).strip().decode()
+    current = sp.check_output(f"git rev-parse HEAD", shell=True, cwd=config.gitdir).strip().decode()
+    message = sp.check_output(f"git log {current} --pretty='format:%C(auto)%h %s (%ad)' -1", shell=True, cwd=config.gitdir).strip().decode()
+    logger.info(f'restore bibliography to {message}')
 
-def _restore_from_backupdir(config):
-    logger.info('restore bibliography')
-    # copy the files to the working directory
-    # backupdir = Path(config.file).parent
-    backupdir = Path(config.gitdir)
-    backupfile = backupdir/'papers.bib'
     if os.path.exists(config.bibtex):
         os.remove(config.bibtex)
-    open(config.bibtex, 'w').write('')
-    if config.backup_files:
-        cmd = f"add {backupfile} --bibtex {config.bibtex} --filesdir {config.filesdir} --rename --copy --no-git"
-    else:
-        cmd = f"add {backupfile} --bibtex {config.bibtex} --filesdir {config.filesdir} --no-git"
-    # return sp.check_call(f"PYTHONPATH={Path(papers.__file__).parent.parent} python3 -m papers {cmd}", shell=True)
-    # Here we avoid starting a new process with re-importing python libs etc
-    logger.info("papers "+cmd)
-    main(cmd.split())
-
-def _git_undo(config):
-    """papers undo using git backup"""
-    # backupdir = Path(config.file).parent
-    backupdir = Path(config.gitdir)
-    backupfile = backupdir/'papers.bib'
-    # keep track of where we come from, for future redos
-    current = sp.check_output(f"git rev-parse HEAD", shell=True, cwd=backupdir).strip().decode()
-    #  now go back
-    config.gitcmd(f"reset --hard HEAD^")
-    futuresfile = backupdir/"futures.txt"
-    open(futuresfile, 'a+').write(current+"\n")
-    _restore_from_backupdir(config)
-
-def _git_redo(config):
-    """papers redo using git backup"""
-    # backupdir = Path(config.file).parent
-    backupdir = Path(config.gitdir)
-    backupfile = backupdir/'papers.bib'
-    # keep track of where we come from, for future redos
-    futuresfile = backupdir/"futures.txt"
-    try:
-        futures = open(futuresfile, 'r').readlines()
-        last = futures[-1].strip()
-    except:
-        last = ""
-    if not last:
-        logger.info("Nothing to redo")
+    shutil.copy(config.backupfile, config.bibtex)
+
+    # Re-name the file according to back-up bibtex
+    if not config.backup_files:
         return
 
-    config.gitcmd(f"reset --hard {last}")
-    futures = futures[:-1]
-    if futures:
-        open(futuresfile, 'w').write("\n".join(futures))
-    else:
-        futuresfile.unlink()
+    biblio = Biblio.load(config.bibtex, config.filesdir)
+    biblio_clean = Biblio.load(config.backupfile_clean, config.filesdir)
+
+    assert len(biblio.entries) == len(biblio_clean.entries)
+
+    for e, e_clean in zip(biblio.entries, biblio_clean.entries):
+        assert e['ID'] == e_clean['ID'], f"{e['ID']} != {e_clean['ID']})"
+        files = biblio.get_files(e)
+        files_clean = biblio_clean.get_files(e_clean)
+        assert len(files) == len(files_clean), f"{e['ID']} :: files {len(files)} != {len(files_clean)})"
+
+        new_files = []
+
+        for f, f_clean in zip(files, files_clean):
+            # broken link in the backup
+            if not os.path.exists(f_clean):
+                logger.debug(f"BACKUP FILE DOES NOT EXISTS: {f_clean} ")
+                logger.debug(f"BACKUP ENTRY: {e_clean['file']} ")
+                logger.debug(f"BROKEN ENTRY: {e['file']} ")
+                logger.warning(f"{e['ID']} :: file link broken => {f} ")
+                new_files.append(f)
+                continue
+
+            # backup file is fine
+
+            # original bibtex link matches something on disk
+            if os.path.exists(f):
+
+                # same file: nothing to do
+                if os.path.samefile(f, f_clean) or checksum(f_clean) == checksum(f):
+                    new_files.append(f)
+
+                else:
+                    logger.warning(f"{e['ID']} :: file found but does not match backup (keep pointer to backup): {f} != {f_clean}")
+                    new_files.append(f_clean)
+
+            # original bibtex link is broken, --restore-file is active
+            elif restore_files:
+                try:
+                    move(f_clean, f, copy=True, interactive=False)
+                    new_files.append(f)
+
+                except Exception as error:
+                    logger.error(f"{error}")
+                    logger.error(f"{e['ID']} :: failed to restore file (keep pointer to backup)")
+                    new_files.append(f_clean)
+                    pass
+
+            # original bibtex link is broken, default without --restore-file : do not do anything
+            else:
+                new_files.append(f_clean)
+
+        biblio.set_files(e, new_files)
+
+    biblio.save(config.bibtex)
+
+
+def _git_reset_to_commit(config, commit, restore_files=False):
+    config.gitcmd(f"reset --hard {commit}")
+    _restore_from_backupdir(config, restore_files=restore_files)
 
-    _restore_from_backupdir(config)
+
+def _git_undo(config, restore_files=False, steps=1):
+    sp.check_call(f"git checkout -B history", shell=True, cwd=config.gitdir)
+    _git_reset_to_commit(config, 'HEAD'+'^'*steps, restore_files=restore_files)
+    # _git_reset_to_commit(config, 'HEAD^', restore_files=o.restore_files)
+
+
+def _git_redo(config, restore_files=False, steps=1):
+    current = sp.check_output(f"git rev-parse HEAD", shell=True, cwd=config.gitdir).strip().decode()
+    futures = sp.check_output(f"git rev-list {current}..main", shell=True, cwd=config.gitdir).strip().decode().splitlines()[::-1]
+    try:
+        future = futures[steps-1]
+    except Exception as error:
+        raise PapersExit("nothing to redo")
+    _git_reset_to_commit(config, future, restore_files=restore_files)
 
 
 def savebib(biblio, config):
@@ -143,6 +217,8 @@ def savebib(biblio, config):
         biblio.save(config.bibtex)
     if config.file and config.git:
         _backup_bib(biblio, config)
+    else:
+        logger.debug(f'do not backup bib: {config.file}, {config.git}')
     # if config.git:
         # config.gitcommit()
 
@@ -150,7 +226,7 @@ def savebib(biblio, config):
 def set_keyformat_config_from_cmd(o, config):
     """
     Given options and a config state, applies the desired key options to the config.
-    """    
+    """
     config.keyformat.template = o.key_template
     config.keyformat.author_num = o.key_author_num
     config.keyformat.author_sep = o.key_author_sep
@@ -186,12 +262,18 @@ def installcmd(parser, o, config):
         o.edit = ans.lower() == 'e'
 
     if not o.edit:
+        if config.local and os.path.exists(config.file):
+            # if we don't do that the local install will take precedence over global install
+            logger.warning(f"remove pre-existing local configuration file: {config.file}")
+            os.remove(config.file)
         config = Config()
 
     if o.local is None:
         if config.local is not None:
+            logger.debug(f'keep config to pre-existing: {config.local}')
             o.local = config.local
         else:
+            logger.debug(f'default to global config')
             # default ?
             o.local = False
 
@@ -203,11 +285,10 @@ def installcmd(parser, o, config):
     default_filesdir = config.filesdir or "files"
 
     if o.local:
-        papersconfig = config.file or ".papers/config.json"
+        papersconfig = config.file or CONFIG_FILE_LOCAL
         workdir = Path('.')
         bibtex_files = [str(f) for f in sorted(workdir.glob("*.bib"))]
-        config.gitdir = config.data = os.path.dirname(papersconfig)
-        
+
         if o.absolute_paths is None:
             o.absolute_paths = False
 
@@ -216,7 +297,7 @@ def installcmd(parser, o, config):
         workdir = Path(DATA_DIR)
         bibtex_files = [str(f) for f in sorted(Path('.').glob("*.bib"))] + [str(f) for f in sorted(workdir.glob("*.bib"))]
         checkdirs = [os.path.join(DATA_DIR, "files")] + checkdirs
-        
+
         if o.absolute_paths is None:
             o.absolute_paths = True
 
@@ -271,16 +352,25 @@ def installcmd(parser, o, config):
     config.bibtex = o.bibtex
     config.filesdir = o.filesdir
     config.file = papersconfig
-    config.gitdir = config.data = os.path.dirname(config.file)
     config.local = o.local
     config.absolute_paths = o.absolute_paths
 
+    # Unless otherwise specified (option not advertized -- help suppressed)
+    # the git directory is centralized in the back up dir.
+    if o.gitdir:
+        config.gitdir = o.gitdir
+
+    elif config.bibtex is not None:
+        from normality import slugify
+        bibi = config.bibtex[:-len(".bib")] if config.bibtex.endswith(".bib") else config.bibtex
+        config.gitdir = os.path.join(BACKUP_DIR, slugify(bibi))
+
     if o.editor:
         config.editor = o.editor
 
     # create bibtex file if not existing
     bibtex = Path(o.bibtex) if o.bibtex else None
-    
+
     if bibtex and not bibtex.exists():
         logger.info(f'create empty bibliography database: {bibtex}')
         bibtex.parent.mkdir(parents=True, exist_ok=True)
@@ -325,32 +415,27 @@ def installcmd(parser, o, config):
     config.backup_files = config.gitlfs
 
     logger.info('save config file: '+config.file)
-    os.makedirs(os.path.dirname(config.file), exist_ok=True)
+    if os.path.dirname(config.file):
+        # typically is current dir = ""
+        os.makedirs(os.path.dirname(config.file), exist_ok=True)
 
     config.git = o.git
 
     config.save()
 
     if config.git:
+        # add a gitignore file to skip gitdir
         if (Path(config.gitdir)/'.git').exists():
             logger.warning(f'{config.gitdir} is already initialized')
         else:
             os.makedirs(config.gitdir, exist_ok=True)
             config.gitcmd('init')
 
-
         if config.gitlfs:
             config.gitcmd('lfs track "files/"')
             config.gitcmd('add .gitattributes')
+            config.gitcmd(f'commit -m "papers install: .gitattribute"', check=False)
 
-        with open(Path(config.gitdir)/'.gitignore', 'a+') as f:
-            lines = f.readlines()
-            if 'futures.txt' not in (l.strip() for l in lines):
-                f.write('futures.txt\n')
-        config.gitcmd('add .gitignore')
-        config.gitcmd(f'add {os.path.abspath(config.file)}')
-        message = f'papers ' +' '.join(sys.argv[1:])
-        config.gitcmd(f'commit -m "new install: config file"', check=False)
         biblio = get_biblio(config)
         _backup_bib(biblio, config)
 
@@ -362,7 +447,7 @@ def _dir_is_empty(dir):
         return not any(it)
 
 def uninstallcmd(parser, o, config):
-    # TODO this is actually never tested.    
+    # TODO this is actually never tested.
     if Path(config.file).exists():
         logger.info(f"The uninstaller will now remove {config.file}")
         os.remove(config.file)
@@ -376,11 +461,11 @@ def uninstallcmd(parser, o, config):
         return
 
     if o.recursive:
-        config.file = search_config([os.path.join(".papers", "config.json")], start_dir=".", default=CONFIG_FILE)
+        config.file = search_config([CONFIG_FILE_LOCAL, os.path.join(".papers", "config.json")], start_dir=".", default=CONFIG_FILE)
         config.file = check_legacy_config(config.file)
         uninstallcmd(parser, o, config)
 
-def check_install(parser, o, config):
+def check_install(parser, o, config, bibtex_must_exist=True):
     """
     Given an option and config, checks to see if the install is done correctly on this filesystem.
     """
@@ -398,7 +483,8 @@ def check_install(parser, o, config):
         parser.print_help()
         print(f"--bibtex must be specified, or {install_doc}")
         raise PapersExit()
-    elif not os.path.exists(config.bibtex):
+
+    if bibtex_must_exist and not os.path.exists(config.bibtex):
         print(f'papers: error: no bibtex file found, do `touch {config.bibtex}` or {install_doc}')
         raise PapersExit()
     logger.info(f'bibtex: {config.bibtex!r}')
@@ -408,7 +494,7 @@ def check_install(parser, o, config):
 
 def addcmd(parser, o, config):
     """
-    Given an options set and a config, sets up the function call to add the file or dir to the bibtex, and executes it.
+    Given an options set and a config, sets up the function call to add the file or all files in the directory to the bibtex, and executes it.
     """
 
     set_nameformat_config_from_cmd(o, config)
@@ -447,7 +533,7 @@ def addcmd(parser, o, config):
                                 **kw)
                 else:
                     raise ValueError(file+' is a directory, requires --recursive to explore')
-                
+
             elif file.endswith('.pdf'):
                 biblio.add_pdf(file, attachments=o.attachment, rename=o.rename, copy=o.copy,
                            search_doi=not o.no_query_doi,
@@ -456,7 +542,7 @@ def addcmd(parser, o, config):
                            **kw)
 
             else: # file.endswith('.bib'):
-                biblio.add_bibtex_file(file, **kw)
+                biblio.add_bibtex_file(file, attachments=o.attachment, rename=o.rename, copy=o.copy, **kw)
 
         except Exception as error:
             # print(error)
@@ -471,10 +557,13 @@ def addcmd(parser, o, config):
     savebib(biblio, config)
 
 def checkcmd(parser, o, config):
+    """
+    Loops over the entire bib file that the Papers install sees, and checks each entry for formatting and for the existance of duplicates.  Then writes the Biblio object back to your Bibtex file.
+    """
     set_keyformat_config_from_cmd(o, config)
 
     biblio = get_biblio(config)
-    
+
     # if o.fix_all:
     #     o.fix_doi = True
     #     o.fetch_all = True
@@ -505,21 +594,21 @@ def filecheckcmd(parser, o, config):
 
     if o.rename:
         biblio.rename_entries_files(o.copy)
-        
+
     savebib(biblio, config)
 
 def redocmd(parser, o, config):
     if config.git:
-        return _git_redo(config)
+        return _git_redo(config, restore_files=o.restore_files, steps=o.steps)
     else:
         undocmd(parser, o, config)
 
 def undocmd(parser, o, config):
     if config.git:
-        return _git_undo(config)
+        return _git_undo(config, restore_files=o.restore_files, steps=o.steps)
 
     logger.warning("git-tracking is not installed: undo / redo is limited to 1 step back and forth")
-    back = backupfile(config.bibtex)
+    back = backupfile_func(config.bibtex)
     tmp = config.bibtex + '.tmp'
     # my = :config.bibtex, config.filesdir)
     logger.info(config.bibtex+' <==> '+back)
@@ -528,6 +617,16 @@ def undocmd(parser, o, config):
     shutil.move(tmp, back)
     # o.savebib()
 
+def restorecmd(parser, o, config):
+    if not config.git:
+        parser.print_help()
+        raise PapersExit('only valid with --git enabled')
+    if o.ref:
+        _git_reset_to_commit(config, o.ref, restore_files=o.restore_files)
+    else:
+        _restore_from_backupdir(config, restore_files=o.restore_files)
+
+
 def gitcmd(parser, o, config):
     try:
         out = sp.check_output(['git']+o.gitargs, cwd=config.gitdir)
@@ -537,7 +636,7 @@ def gitcmd(parser, o, config):
         parser.error('papers failed to execute git command -- you should check your system git install.')
 
 def doicmd(parser, o):
-    print(extract_pdf_doi(o.pdf, image=o.image))    
+    print(extract_pdf_doi(o.pdf, image=o.image))
 
 def fetchcmd(parser, o):
     print(fetch_bibtex_by_doi(o.doi))
@@ -665,6 +764,20 @@ def listcmd(parser, o, config):
             e['keywords'] = ", ".join(keywords)
         savebib(biblio, config)
 
+    elif o.add_files:
+        if len(entries) != 1:
+            raise PapersExit("list only one entry to use --add-files")
+        e = entries[0]
+        files = biblio.get_files(e)
+        for f in o.add_files:
+            if not os.path.exists(f):
+                raise PapersExit(f"file {f} does not exist")
+        files.extend(o.add_files)
+        biblio.set_files(e, files)
+        if o.rename:
+            biblio.rename_entry_files(e, copy=o.copy)
+        savebib(biblio, config)
+
     elif o.edit:
         otherentries = [e for e in biblio.db.entries if e not in entries]
         try:
@@ -675,7 +788,7 @@ def listcmd(parser, o, config):
             return
 
         savebib(biblio, config)
-        
+
     elif o.fetch:
         for e in entries:
             biblio.fix_entry(e, fix_doi=True, fix_key=True, fetch_all=True, interactive=True)
@@ -686,6 +799,12 @@ def listcmd(parser, o, config):
             biblio.db.entries.remove(e)
         savebib(biblio, config)
 
+    elif o.open:
+        for e in entries:
+            for f in biblio.get_files(e):
+                logger.info(f"opening {f} ...")
+                view_pdf(f)
+
     elif o.field:
         # entries = [{k:e[k] for k in e if k in o.field+['ID','ENTRYTYPE']} for e in entries]
         for e in entries:
@@ -698,21 +817,26 @@ def listcmd(parser, o, config):
             tit = e.get('title', '')[:60]+ ('...' if len(e.get('title', ''))>60 else '')
             info = []
             if e.get('doi',''):
-                info.append('doi:'+e['doi'])
+                info.append(link(f"https://doi.org/{e['doi']}", 'doi:'+e['doi']))
             n = _nfiles(e)
             if n:
-                info.append(bcolors.OKGREEN+('files:' if n > 1 else 'file:')+str(n)+bcolors.ENDC)
+                files = parse_file(e.get('file',''), relative_to=biblio.relative_to)
+                file_link = f"file:///{Path(files[0]).resolve()}"
+                ansi_link = link(file_link, f'{"file" if n == 1 else "files"}:{str(n)}')
+                info.append(bcolors.OKGREEN+ansi_link+bcolors.ENDC)
             if e.get('keywords',''):
                 keywords = parse_keywords(e)
                 info.append(bcolors.WARNING+" | ".join(keywords)+bcolors.ENDC)
             infotag = '('+', '.join(info)+')' if info else ''
             print(key(e), tit, infotag)
+
     else:
         print(format_entries(entries))
 
+
 def statuscmd(parser, o, config):
     print(config.status(check_files=not o.no_check_files, verbose=o.verbose))
-    
+
 
 
 def get_parser(config=None):
@@ -930,7 +1054,7 @@ def get_parser(config=None):
 
     # list
     # ======
-    listp = subparsers.add_parser('list', description='list (a subset of) entries',
+    listp = subparsers.add_parser('list', description='list (a subset of) entries in the existing bib file',
         parents=[cfg])
 
     listp.add_argument('fullsearch', nargs='*', help='''Search field. Usually no quotes required. See keywords to search specific fields. All words must find a match, unless --any is passed.''')
@@ -976,6 +1100,10 @@ def get_parser(config=None):
     grp.add_argument('--edit', action='store_true', help='interactive edit text file with entries, and re-insert them')
     grp.add_argument('--fetch', action='store_true', help='fetch and fix metadata')
     grp.add_argument('--add-keywords', '--add-tag', nargs='+', help='add keywords to the selected entries')
+    grp.add_argument('--add-files', nargs='+', help='add files to the selected entries (only one entry must be listed)')
+    grp.add_argument('--rename', action='store_true', help='rename added file(s) into files folder. Used together with --add-files')
+    grp.add_argument('--copy', action='store_true', help='copy added file(s) into files folder. Used together with --add-files --rename')
+    grp.add_argument('-o', '--open', action='store_true', help='open attachments (if any)')
 
     # grp.add_argument('--merge-duplicates', action='store_true')
 
@@ -1005,8 +1133,16 @@ def get_parser(config=None):
 
     # undo
     # ====
-    undop = subparsers.add_parser('undo', parents=[cfg], help='this command is modified and more powerful if git-tracking is enabled (infinite memory vs back-and-forth switch)')
-    redop = subparsers.add_parser('redo', parents=[cfg], help='this command is modified and more powerful if git-tracking is enabled (infinite memory vs back-and-forth switch)')
+    _restorep = argparse.ArgumentParser(add_help=False)
+    _restorep.add_argument('--restore-files', action='store_true', help='Use this option to restore files that have been renamed. By default the file link points to the back-up repository. This command has no effect without --git-lfs, and will result in broken file links.')
+
+    _stepsp = argparse.ArgumentParser(add_help=False)
+    _stepsp.add_argument('-n', '--steps', type=int, default=1, help='number of times undo/redo should be performed')
+
+    undop = subparsers.add_parser('undo', parents=[cfg, _restorep, _stepsp], help='Undo changes on bibtex (if --git is not enabled, only back and forth with last modification). If --git-lfs is enabled, the file entry may differ if it does not exist on disk any more, unless --restore-files was passed.')
+    redop = subparsers.add_parser('redo', parents=[cfg, _restorep, _stepsp], help='Redo changes on bibtex (if --git is not enabled, this has the same effect as papers undo)')
+    restorep = subparsers.add_parser('restore-backup', parents=[cfg, _restorep], help='Restore bibtex from backup. Also restore files if --restore-files if passed (--git-lfs only).')
+    restorep.add_argument('--ref', help='Optional: restore specific commit (execute `papers git whatchanged` to obtain appropriate reference)')
 
     # git
     # ===
@@ -1021,8 +1157,11 @@ def get_parser(config=None):
 
 def main(args=None):
     papers.config.DRYRUN = False  # reset in case main() if called directly
+    if args is not None:
+        # used in the commit message
+        sys.argv = sys.argv[:1] + args
 
-    configfile = search_config([os.path.join(".papers", "config.json")], start_dir=".", default=CONFIG_FILE)
+    configfile = search_config([CONFIG_FILE_LOCAL, os.path.join(".papers", "config.json")], start_dir=".", default=CONFIG_FILE)
     configfile = check_legacy_config(configfile)
     if not os.path.exists(configfile):
         config = Config()
@@ -1079,6 +1218,8 @@ def main(args=None):
         check_install(subp, o, config) and undocmd(subp, o, config)
     elif o.cmd == 'redo':
         check_install(subp, o, config) and redocmd(subp, o, config)
+    elif o.cmd == 'restore-backup':
+        check_install(subp, o, config, bibtex_must_exist=False) and restorecmd(subp, o, config)
     elif o.cmd == 'git':
         if not installed:
             subp.error('papers must be installed to use git command')
@@ -1099,10 +1240,17 @@ class PapersExit(Exception):
     pass
 
 
+def main_clean_exit(args=None):
+    try:
+        main(args)
+    except PapersExit as error:
+        if logger.getEffectiveLevel() == logging.DEBUG:
+            raise
+        if error.args:
+            logger.error(str(error))
+        sys.exit(1)
+
 if __name__ == "__main__":
     # we use try/except here to use a clean exit instead of trace
     # test and debugging may use main() directly for speed-up => better to avoid sys.exit there
-    try:
-        main()
-    except PapersExit:
-        sys.exit(1)
+    main_clean_exit()

papers/_version.py

@@ -1,4 +1,16 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '2.4'
-__version_tuple__ = version_tuple = (2, 4)
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '2.6'
+__version_tuple__ = version_tuple = (2, 6)