Using External Git Version Control with Altium Designer

Parent page: Using External Version Control

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.

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.

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 repository

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 Scheducled 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 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.

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 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)).