Working with a File's Local History in the MPLAB® X IDE

Last modified by Microchip on 2024/06/24 06:35

The Local History feature fills the gap between a full version control system and no version control at all. Every time you make changes to a file and save or build it, the Local History feature will keep a copy of one or more previous saved versions for a predetermined length of time (seven days by default). You will then be able to do a diff comparison between the current version and any past version in its buffer.


The intent of Local History is to keep track of the changes a developer make to a program before having something worthy of committing to the version control system. It is also extremely useful for the independent or small company developer without access to a version control system as it provides similar features. The primary difference is that it only works within the IDE, so it cannot be used to keep track of changes from other team members on other computers. The history is local to the computer on which it was established and will not stay with a project that is moved to another computer. If you need this functionality across multiple systems, a true version control system such as Subversion is a more appropriate MPLAB X subversion tool.

Enabling Local History

Local History is enabled by default with a buffer of 7 days. So there is nothing you need to do to take advantage of it immediately.
To disable Local History, set the number of days to keep history to zero.

Back to Top

Adjusting Local History time span

From the main menu, select Tools > Options
In the window that opens, click on the Team icon  Team icon
Select the Versioning tab.
Select History from the list on the left side.

Change the number of days and click the OK button to accept the change.

Adjusting Local History time span

Back to Top

How to view a file's Local History

Either right-click on an open file's tab in the editor or right-click on a file in the project tree. Then select Local History ▸ Show Local History from the pop-up menu.

Show Local History


Select from the file menu in the Project Tree

File Menu in Project Tree

Then, in the new tab that opens up in the editor, select the old version you want to compare in the top part of the pane. In the lower half of the pane, the old version will be shown on the left and the current version on the right. The built in diff utility clearly shows you where the files differ and makes it easy to cancel new changes or revert to older code.

MPLAB X IDE Diff Utility

Back to Top

How to revert a file or parts of a file to an earlier version

There are three distinct actions you may take in the Local History view to revert the current file to an earlier version.

To remove code that didn't exist in the older file but was added to the current file, click the little red "X" in the margin by the line numbers.

Remove code in MPLAB X IDE Diff Utility

To insert code from an older file into the current file, click on the blue arrow in the margin by the line numbers.

Insert code in MPLAB X IDE Diff Utility

To revert the entire current file to an older version, click on the blue arrow in the middle-top of the diff window.

Revert File in MPLAB X IDE Diff Utility

Back to Top

How to add a label to a local history entry

The local history list contains two columns: Version and Label. The label can be used to annotate each version of the file. Simply click in the blank space in the label column and begin typing.

Add a label to a local history entry

Back to Top