Using External Git Version Control with Altium Designer

Git-type repositories are created outside of Altium Designer, and the content of a local working Git repository is accessed by opening files from its host folder. The management of both remote and local working Git repositories is typically through company systems and external Git tools, while file-level operations (Commit, Push, Update, etc.) are handled in the Altium Designer editing environment.

  • Before using Git Version Control for design projects, ensure that the VCS Provider – Git Extension is installed in Altium Designer. This extension is installed by default but can be accessed in the software's Extensions and Updates view.
  • Note that Git repositories are handled outside Altium Designer.
  • While there is a range of data transfer protocols offered by the Git VCS, Altium Designer currently supports the HTTP/HTTPS protocol only for connections between a local Git repository and its remote master repository. Learn more about Protocols.
  • When pushing changes to a project that is under an external Git VCS and the repository in which that design resides uses the SSH protocol for connection, you will be offered the choice to try to have that repository updated to use the supported HTTPS connection protocol instead (provided the repository itself supports this protocol).
  • Note that a personal access token must be used when working with a GitHub-hosted project from Altium Designer. Otherwise, an authentication error will appear when pushing the project to the repository. Learn more about Creating a personal access token.

Add to Git Version Control

As a distributed version control system, Git uses a different workflow to that of SVN, although the difference is minimal when working with established project files in Altium Designer. In short, Git applies the transfer of data between multiple repositories, rather than focusing on the dependency of a single repository target.

► See the Git website for more information and Version Control Essentials for an overview of the principles that apply.

A Git VCS system is typically based on a centralized, remote Git server that can host multiple Git repositories as needed. The fast, lightweight nature of Git lends itself to the practice of creating a remote repository for each project, which can then be cloned (copied) as a working repository to any user that is working on the project. Updated files in a user's working Git repository are then ‘pushed’ to the remote repository on the Git server to achieve synchronization.

A remote repository can also be a shared type (bare) Git repository in a convenient location, such as on a shared network resource. To create a shared remote Git repository with Git command line tools, use the git init --bare command.

The method used to establish an Altium Designer project in a Git system will depend on company infrastructure and practice and will involve tools and processes that are external to Altium Designer. Once a project is in the version control system and made available as a local working repository, however, working with a Git VCS in Altium Designer is virtually the same as working with a SVN VCS.

Add a Project to Git

By way of example, an existing Altium Designer project can be added to a local Git repository using the basic Git command line tools. With this approach, the project folder becomes the local (working) Git repository, and this is linked and ultimately updated to an available remote Git repository.

Here, the tools are used to:

  1. Create (initialize) the working Git repository in the project folder.
  2. Add the project files to Git version control. The *.* file spec adds files but not folders.
  3. Specify the link reference to the shared remote Git repository on a web server. PCrepo is a nominated local alias of the remote repository URL.

Project being added to a local Git repositoryProject being added to a local Git repository

The following Commit and Push processes could also be done using the command line tool, but in this example the steps are completed in Altium Designer, as outlined below.

When the project is opened in Altium Designer, the status of its files in the Projects and Storage Manager panels is Scheduled for Addition (). When then committed to the working repository, the files change to the Ahead of Server status () since they are not, as yet, under version control in the remote Git repository.

  Files scheduled as Scheduled for Addition and Ahead of Server

The Push command will update the local repository files to the remote Git server, which may request valid credentials for the targeted repository – a once off process. Note that the Commit and Push operations can be called in one action in Altium Designer (), but are completed in individual steps here for explanation purposes.

Files are updated following the request of valid credentialsFiles are updated following the request of valid credentials

The Altium Designer project, which is now fully under Git version control, becomes available to other users from the remote Git repository. Another user may clone the repository to their local machine, for example, and ultimately push their edited files back to the remote repository in a collaborative workflow.

Note that the above process is just a manual example of how a project may be added to a remote Git server. Established Git VCS installations are likely to have GUI tools or automated systems in place, under admin control, that make the process of establishing and retrieving working VCS projects straightforward.

An Altium Workspace is an example of an advanced server-based system that uses a Git repository with automated functions that support transparent VCS interaction.

Clone a Git Repository

A local project that has been added to Git Version Control can be edited by Altium Designer from the project's local folder (the working repository), and the committed changes are then updated to the remote Git repository. The local repository and the remote repository are linked and ultimately synchronized by a VCS Push command.

Other users who wish to collaborate on the design can access the project by cloning the remote Git repository to a local working repository. While the approach to accessing files from a remote Git repository will differ with company systems and methods, a basic way to clone the content from a remote repository to a local working repository is by using the Git command; git clone [remote repository URL] [target working repository folder], as shown in the below image.

Committed changes updated to the remote Git repositoryCommitted changes updated to the remote Git repository

The process will replicate the shared remote repository as a local working repository and automatically check out the latest (HEAD) revision from the master branch. The files may then be edited, saved, and committed to VCS in Altium Designer, and ultimately pushed back to the remote Git repository.

Connecting to an Existing Git Repository

Altium Designer offers no controls for creating a new Git repository or connecting to an existing one. However, you can effectively connect to an existing repository of this type by other means (that are the traditional technique favored by the Git user-ship). To do so:

  1. Create your remote Git repository, or access your company's external repository – in which your Altium Designer projects are stored.
  2. Clone the repository to make your local working Git repository.
  3. Open an Altium Designer project from the local repository.

Altium Designer will recognize that the project is under version control in a Git-based repository, and provide VCS-related statuses, and commands/functions to work with the files (including Commit (to local working Git repository) and Push (from local Git repository to remote Git repository)).

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
Note

The features available depend on your Altium product access level. Compare features included in the various levels of Altium Designer Software Subscription and functionality delivered through applications provided by the Altium 365 platform.

If you don’t see a discussed feature in your software, contact Altium Sales to find out more.

Content