Managing Project Documents in Altium Designer

Projects Panel

The Projects panel displays all projects that are currently open and their constituent documents and structure. The panel's right-click context menus offer the majority of commands required for working with design documents.

The Projects panel

Note that the presentation of documents in the Projects panel does not reflect how they are stored on the hard drive or elsewhere. The panel's contents can be considered as a logical representation of the project, whereas the physical location and organization of the document file storage (and its type) are up to you – the documents might be stored in a folder on your local machine or a LAN, and of course, hosted in a version-controlled repository provided by a basic Git/SVN VCS system or a fully managed system such a Workspace.

The behavior of the Projects panel can be configured using the options on the System – Projects panel page of the Preferences dialog. These options can also be accessed using the  control at the top of the panel.

When connected to a Workspace, the Workspace icon ( / ) is shown next to the uppermost entry of this Workspace. When a Workspace project is opened, its entry is shown with an indicative icon, such as  for a PCB project. When the local working copy of a project is opened but the Workspace where the project resides is not connected, a grayed-out Workspace icon ( / ) will appear, and the project icon will change (e.g. it appears as  for a PCB project).

A Workspace project can also be shared with you without inviting you to the team of the Workspace where this project resides. A project that has been opened from shared access is indicated by an associated Shared with me label with the icon next to it.

If a project was shared with you so you can only view it, the View Only label will be shown next to the project entry in the panel to indicate this.

An indication of a project shared with you to view only.

Local projects are listed under the entry of the project group ( *.DsnWrk) – either the default one (Project Group 1.DsnWrk), or one you have created or opened.

To access the context menu regarding your currently connected Workspace, right-click on your Workspace name or click the  control at its far right. These commands include:

• Open Project – opens the Open Project dialog.
• Create Project – opens the Create Project dialog.
• Show in Explorer – opens the Explorer panel.
• Show in Web Browser – opens the Projects page of the Workspace's browser interface in your default browser.
• Sign out – signs you out of the Workspace.
• Sign in – signs you in to the Workspace. This command is available provided that you have at least one Workspace item (e.g., project) opened in the Projects panel and you are currently disconnected from the Workspace where this item resides.

You must be connected to a Workspace to access these commands. When signed out of a Workspace, right-click the Workspace you want to connect to, and click the Sign In command.

Project Documents Tree

When you open an existing project or create a new one, its entry will appear in the Projects panel. Any existing documents that are part of a project (and any new ones that have been added) will appear under sub-folders according to their purpose and/or type. For example, the following common folders and content document types can appear under a project:

• Source Documents – core design documents such as schematics, PCBs, etc.
• Settings – provides various files used within the project, including Output Job Files, Harness Definitions Files, and Annotation Documents, among other pertinent files.
• Libraries – local source library documents. Documents are further subdivided based on library type (e.g., schematic libraries, PCB libraries, etc.).
• Documentation – additional documents that have been added to the project, of a type that is known by Altium Designer (e.g., text, PDF, etc.).
• Other Documents – additional documents that have been added to the project, of a type that is not known by Altium Designer. These can be opened by Altium Designer if the owner application is known by Windows (e.g., Word documents, Excel spreadsheets, etc.).
• Generated – documents generated as output. Documents are further subdivided based on type (e.g., BOM documents, text documents, etc.). As project output is generated, the corresponding sub-folders in the main tree will be created and become populated.
• Components – this folder lists each component and the number of components in each group. Validate the project if this folder does not appear (Project » Validate). Components are grouped by the first letter in the designator by default - right-click on the entry for a component (or component grouping folder) and choose the Component Grouping command from the context menu to quickly access the Components Grouping controls for the Projects panel and change the style of grouping, or disable grouping, as required. See the Searching for Components and Nets in the Project Structure section of the Creating Circuit Connectivity in Your Schematics page to learn more.
• Nets – this folder lists each net used in the project. Validate the project if this folder does not appear (Project » Validate). See the Searching for Components and Nets in the Project Structure section of the Creating Circuit Connectivity in Your Schematics page to learn more.

Documents that are stored in the project folder or a sub-folder of the project folder are associated in the project file using relative referencing. Documents that are stored in a different folder path are associated in the project file using absolute referencing. These documents include a small arrow in the bottom corner to indicate that they are linked to the project, as shown by the file in the image above.

Notes on working in the documents tree:

• Any documents that are independent of a project will appear as Free Documents and will appear under corresponding sub-folders. By right-clicking on a free document and choosing the Add to Project <ActiveProjectName> command from the context menu, you can add a currently open free document to the active project. Alternatively, you can drag and drop it onto the required project name, in the Projects panel.
• Along with allowing multiple documents to be open for editing, the environment also supports multiple projects being open at the same time. These could be related or unrelated projects.
• Documents in the Projects panel are automatically arranged in logical groups or 'folders', such as Source Documents (Schematic, PCB, etc.), Settings documents (Harness, Outjob, etc.,) and, in the case of a hierarchical design, top-level schematic documents. The documents within each folder group are displayed by default in the order they were added but can be dragged and dropped to a new order position within the group.
• In the case of a new hierarchical design, the parent-child relationship between documents will be displayed in the panel. Note that the connectivity relationships cannot be defined by dragging and dropping schematic documents since the inter-sheet connections and design hierarchy are in fact defined by Sheet Symbols and Port definitions.
• Right-click a project document sub-folder, whether expanded or closed, to access additional document management commands, such as opening, closing, or saving all documents within the focused project document sub-folder.
• Documents can be transferred between projects in the panel by clicking and dragging. The document does not have to be dragged into the correct sub-folder; it will be placed correctly within the project structure automatically.
• The keyboard shortcuts Up Arrow, Home, End, and Down Arrow can be used to display the previous, first, last, and next entry in the panel, respectively. Use the Right Arrow and Left Arrow keys to expand and collapse a top-level entry or its sub-folder, respectively.
• To cross-probe from the selected component or net entry in the Projects panel, to that entity on the schematic or PCB document of the parent PCB design project, right-click on the entry and choose the Cross Probe to Schematic or Cross Probe to PCB command from the context menu.
• To open an instance of Windows Explorer, at the location where a project document is stored, right-click its entry in the Projects panel and select the Explore command. For the document focused in the Projects panel, it can be done by clicking the  control at the top of the panel.

Project Options

An existing or newly created Project is associated with a range of Option settings that are specific to that project. These are stored in the project file (*.PrjPcb, for example) and will vary depending on the type of project.

The option settings are configured in the Project Options dialog, which can be accessed from Project » Project Options on the main menu or by right-clicking on the project name in the Projects panel and then selecting Project Options from the context menu. For the project focused in the Projects panel, the dialog can be accessed by clicking the  control at the top of the panel.

Other project settings that are defined in other dialogs and then stored in the project file include:

• Schematic annotation settings.
• Output settings such as reports, print, Gerber, and so on. Note that these are the output settings accessed via the schematic or PCB editor menus, rather than the output settings defined in an OutJob document.

Indicating Document Status

As you work with project documents in Altium Designer, the Projects panel provides a visual summary of which document files are modified or saved through status icons that are associated with each design document, and the main project file. This provides a quick visual summary of which documents are modified, saved, whether they are Workspace or local, and their version control status. The document icons and meanings are listed below.

Open/Modified Status Icons

[blank]	The document is closed.
	Open – The document is open as a tabbed document in the design editor window.
	Open/Modified – The document is open and has been modified (yet to be saved). A modified document is flagged by an asterisk suffix next to its entry in the Projects panel. A modified document also has an asterisk next to its name in its open document tab (or on the associated pop-up menu if documents are grouped).
	The document file is open and locked by this instance of Altium Designer.
	The document file is open and has been locked by another instance of Altium Designer.
	The document is being edited by another user. This status condition is enabled by the Collaborators Visualization & Conflict Prevention feature.
	The document being edited by another user is currently open in the editor. This status condition is enabled by the Collaborators Visualization & Conflict Prevention feature.
	The document is missing (learn more about missing documents).

Version Control Status Icons

The version control system essentially monitors and compares the files in the working folder to their counterparts in the design repository. Altium Designer both requests and exchanges information with the version control system via its VCS interface, and responds to the comparative file status conditions accordingly. In practice, this manifests itself in the Projects file icons, through a range of VCS alerts, and by appropriate changes in the available file management commands.

The icons and their meaning are as follows:

[blank]	N/A	The file is not under version control in a VCS repository,
	No modification	The local copy of the file matches the file in the repository and is up to date.
	Scheduled for Addition	A file has been added to version control but not yet Committed (checked in) to the VCS repository.
	Modified	The local copy of the file has been modified and saved to the working folder. Commit the file to create a new revision in the repository.
	Out of date	The local copy of the file (in the working folder) is older than its counterpart in the repository and is therefore out of date. Use the Update or Update Whole Project command from the History & Version Control right-click menu of the Projects panel or the Projects » History & Version Control main menu to retrieve the latest file from the repository or save the file, which will create a Conflict condition.
	Conflict	Another user has committed the file before you have committed your own edited and saved version of that file. Use the Version Control Update or Resolve command to determine which version of the file will become the latest revision in the repository.
	Ahead of server (Git)	The file in the local working repository is newer than its counterpart in the remote Git repository. This occurs when a local file has been modified, saved and committed to the local repository, but not yet Pushed to the remote repository.
	Scheduled for Deletion	The project file has been removed from version control and will be deleted from the VCS repository and database during the Version Control Commit process. This icon also appears when a file is missing from the local working folder (it has been deleted, renamed or moved), which is resolved by re-populating the folder from the repository with the History & Version Control » Update command.
	Merged	The PCB document has been merged with a newer revision from the repository using the PCB CoDesign panel. Commit the project to the Workspace to save the merged PCB document to the Workspace's repository.

Change Project Document Order

Documents in the Projects panel are automatically arranged in logical groups or 'folders', such as Source documents (Schematic, PCB, etc.), Settings documents (Harness, Outjob, etc.,) and in the case of a hierarchical design, top-level schematic documents. The documents within each folder group are displayed, by default, in the order they were added, but can be dragged and dropped to a new order position within the group.

In the case of a new hierarchical design, the parent-child relationship between documents will be displayed in the Projects panel. Note that the connectivity relationships cannot be defined by dragging and dropping schematic documents since the inter-sheet connections and design hierarchy are in fact defined by Sheet Symbols and Port definitions.

► For more information about project hierarchy, see Creating Connectivity and the Net Identifier Scope section in the Options tab of the Project Options dialog.

Document Renaming

You can directly change the name of any of PCB project constituent design files (*.PcbDoc, *.SchDoc, etc.), the PCB project itself (*.PrjPcb) or the project group (*.DsnWrk) by using the Rename command – available from the right-click context menu for a project in the Projects panel.

Examples of renaming a project and one of its design files, locally from within Altium Designer. Those changes will be synchronized with the Workspace when you save and send the changes to that Workspace.

With renaming performed, save the changes to the Workspace using the Save to Server command (available from the same context menu for the project). File rename synchronization is maintained between the local working copy of the project and its counterpart in the Workspace. Additionally, when the project file name has been renamed and the project saved to the server, the Workspace automatically changes the managed project's Name parameter to match.

Conversely, when the name of a managed project is updated through the Workspace's browser interface, the change is propagated to Altium Designer when the project is next opened.

To edit the properties of an existing managed project in the Workspace, select its entry on the Projects page, click the control above the listing of projects, and choose the Edit entry on the associated menu. Change the name for the project in the subsequent Edit Project window that appears.

When the updated project is opened in Altium Designer (File » Open Project), an initial dialog provides the option to align the local project file name with the new project Name, or force the server project Name to match the existing project file name.

Options available if you have renamed the project on the Workspace side.

Share Documents Between Projects

Because an Altium Designer project defines and saves links to stored document files, any number of projects can be created that link to those same document files.

While this may be a convenient way to re-use established design documents – say, including a standard power supply schematic in several projects – it is not recommended practice because a change in the document will affect all projects it is linked to. A far better approach for design reuse is to establish and apply Managed Sheets.

► For more information about design document reuse and Managed Sheets, see the Managed Sheets page.

Managing Missing Documents

If a project document defined within the project file is not found within the project folder (for example, the document was removed from within Windows Explorer), it is considered missing. Upon opening a project containing a missing file, a corresponding notification will be shown in the Messages panel. The document entry will be grayed out and marked as missing with a distinguishing icon in the Projects panel.

Associated commands are available that give you full control over handling missing documents. Use the right-click menu of a missing document in the Projects panel to remove the selected or all missing files from the project or to update the path to the file (i.e. to replace the missing file with a selected one). For a project under version control, you also can revert local modifications to restore a missing file from the project's VCS repository.

When adding an existing file to the project using the Add Existing to Project command from the project entry's right-click menu and the name and the path of the file being added are the same as the name and the path of a missing file (which is possible when, for example, the missing file was added to the project folder after opening the project in Altium Designer), a confirmation dialog will open asking if you would like to replace the missing file with the selected one.

Compare Local Documents with Commit or Release Data

For projects hosted by a Workspace, you can compare locally saved schematic, PCB (for an Altium 365 Workspace only) and BOM documents with the data of a commit or release of this project. Commands for selecting a required data set with which the local documents should be compared can be chosen from the following locations:

• The History & Version Control » Compare right-click menu of the project or project document in the Projects panel.
• The Compare button menu in the Save to Server dialog.
• The control menu of the Local Changes tile of the Project History view.

❯ ❮

Javascript

When the Latest Commit or Latest Release command is selected, the project data comparison with those from the latest commit/release entry will start. When the Select Commit or Release command is selected, the Project History view will open for the selected project. Select the tile of a commit or release to compare the locally saved data with the data of this commit/release.

Once complete, the comparison results are presented in the Compare view, which opens as a new tab in your default browser.

Clipboard Panel

To store and display copied objects that can be added (pasted) to Altium Designer documents at any stage, allowing for multiple copy/paste operations, the Clipboard panel can be used.

View and apply (paste) Clipboard panel content for all design data types.