BIM
PYREVIT
CODE
-2023-

Creating and installing a clone of pyRevit

Adding extensions to pyRevit is as easy as creating the proper folder structure in a monitored directory. If you want to customize the main tab or alter base extensions, it's a little more involved

The organization and display of extensions for pyRevit is governed by the file hierarchy they are found in. pyRevit looks for keywords in the directory names ('.extension', '.tab', etc.) and then builds the GUI around your script. For example, this is the minimum viable directory structure for a button called 'myCommand,' which will appear in 'myPanel' on 'myTab':

myExtension.extension\
   myTab.tab\
      myPanel.panel\
         myCommand.pushbutton\
            -script.py
            -icon.png

Stock pyRevit monitors the folders indicated under settings>extensions and adds extensions it finds in a new tab in the ribbon alongside the one for built-in extensions (the 'pyRevit' tab). This makes experimenting with your own extensions easy, as once they are found, the script files can be updated without reloading or restarting. Your extensions are kept tidy and separate from what came with pyRevit. Creating a new extension can be as easy as copying the entire '*.extension' folder of an existing one.

This works great if you want to add functionality, but what if you want to do something like strip out irrelevant tools to deploy a leaner, minimized version of pyRevit to your team? What if you want to re-organize the toolbar to make sense in the context of your organization? You could clone the repository and deploy your own version manually after uninstalling the stock version, but you'll quickly find this cumbersome, especially during development and testing. The solution is to use the pyRevit CLI (command line interface) to manage the cloning and installation for you.

pyRevit CLI comes with pyRevit. Assuming you already have pyRevit installed, open a command prompt and type:

pyrevit clones

You should get something back that looks like this:

==> Registered Clones (full git repos)
TFG_pyRevit | Branch: "master" | Version: "4.8.12.22247+0031:691bb1b" | Path: "D:\Scripts\TFG_pyRevit"
==> Registered Clones (deployed from archive/image)
master | Deploy: "basepublic" | Branch: "master" | Version: "4.8.12.22247+0031" | Path: "C:\Program Files\pyRevit-Master"

You won't have the section under "Registered Clones(full git repos)", which is what we're going to change. Refer to the documentation for managing pyRevit clones. The exact command will differ based on whether the source of your new code is the pyRevit repository, your own repository, or a local file. In my case, I already had a repository setup on GitHub with some small alterations so I could see when my changes took effect. My command looked like this:

pyrevit clone TFG_pyRevit --source="<my_private_repos_URL>" --dest="D:\scripts" --branch=master --username='<my_username>' --password='<my_password>'

The destination for the clone can be anywhere convenient, but don't attempt to replace your existing installation. This is standard Git stuff, but by doing it with the pyRevit CLI, pyRevit is aware of this copy and is able to manage it. We now have our version installed, which you can check by running 'pyRevit clones' again, but the new version is not attached to any version of Revit. To attach it, first run

pyrevit attached

which will return something like:

==> Attachments
basepublic | Product: "Autodesk Revit 2023" | Engine: IPY277 (277) | Path: "C:\Program Files\pyRevit-Master" | AllUsers

I have you do this so that you can check the engine used. You are supposed to be able to use the keyword 'latest' in place of the engine name in the next command, but this wasn't working for me, so I instead specified the same engine used previously. You should do the same, running:

pyrevit attach <name_of_your_clone> <name_of_engine> --installed

#example:
#pyrevit attach TFG_pyRevit IPY277 --installed

#command that didn't work for me:
#pyrevit attach TFG_pyRevit latest --installed

This attaches your new clone to all installed versions of Revit. You can check this by running 'pyrevit attached' again. If you need something more specific to happen, check out the documentation for attaching pyRevit clones to Revit. The next time you start Revit, your new clone should appear in place of stock pyRevit.

When your repository has updates you need to deploy, run

pyrevit clones update <name_of_your_clone>

Since pyRevit CLI comes along with pyRevit, you can easily distribute batch files that update everyone on your team to the latest version or to opt them in as beta testers. An example workflow might be to install pyRevit, clone both your company's official version and development branch, and leave batch files on a network drive that let users attach either at will.

If your organization has multiple disciplines, another workflow could be using a batch file to deploy versions of pyRevit that have been customized to each user's discipline.

-Published 12 pm Mon, Feb 6 2023-