Simple local history manager built on libgit2. More...

#include <local_history.h>

Public Member Functions
	LOCAL_HISTORY ()

	~LOCAL_HISTORY ()

bool	Init (const wxString &aProjectPath)
	Initialize the local history repository for the given project path.

bool	CommitSnapshot (const std::vector< wxString > &aFiles, const wxString &aTitle)
	Commit the given files to the local history repository.

bool	CommitFullProjectSnapshot (const wxString &aProjectPath, const wxString &aTitle)
	Commit a snapshot of the entire project directory (excluding the .history directory and ignored transient files) to the local history repository.

void	RegisterSaver (const void *aSaverObject, const std::function< void(const wxString &, std::vector< HISTORY_FILE_DATA > &)> &aSaver)
	Register a saver callback invoked during autosave history commits.

void	UnregisterSaver (const void *aSaverObject)
	Unregister a previously registered saver callback.

void	ClearAllSavers ()
	Clear all registered savers.

bool	RunRegisteredSaversAndCommit (const wxString &aProjectPath, const wxString &aTitle, const wxString &aTagFileType=wxEmptyString)
	Run all registered savers and, if any staged changes differ from HEAD, create a commit.

bool	RunRegisteredSaversAsAutosaveFiles (const wxString &aProjectPath)
	Run all registered savers and write their output to autosave files instead of committing to the local history repository.

std::vector< std::pair< wxString, wxString > >	FindStaleAutosaveFiles (const wxString &aProjectPath) const
	Enumerate autosave files newer than their corresponding source files for the project at `aProjectPath`.

void	RemoveAutosaveFiles (const wxString &aProjectPath) const
	Remove every autosave file under the project at `aProjectPath` regardless of which source it shadowed.

void	RemoveAutosaveFiles (const wxString &aProjectPath, const std::vector< wxString > &aSourcePaths) const
	Remove only the autosave files corresponding to `aSourcePaths`.

void	NoteFileChange (const wxString &aFile)
	Record that a file has been modified and should be included in the next snapshot.

bool	CommitPending ()
	Commit any pending modified files to the history repository.

bool	HistoryExists (const wxString &aProjectPath)
	Return true if history exists for the project.

bool	TagSave (const wxString &aProjectPath, const wxString &aFileType)
	Tag a manual save in the local history repository.

bool	CommitDuplicateOfLastSave (const wxString &aProjectPath, const wxString &aFileType, const wxString &aMessage)
	Create a new commit duplicating the tree pointed to by Last_Save_<fileType> and move the Last_Save_<fileType> tag to the new commit (used when user discards changes).

bool	EnforceSizeLimit (const wxString &aProjectPath, size_t aMaxBytes, PROGRESS_REPORTER *aReporter=nullptr)
	Enforce total size limit by rebuilding trimmed history keeping newest commits whose cumulative unique blob sizes fit within limit.

bool	HeadNewerThanLastSave (const wxString &aProjectPath)
	Return true if the autosave data is newer than the last manual save.

wxString	GetHeadHash (const wxString &aProjectPath)
	Return the current head commit hash.

bool	RestoreCommit (const wxString &aProjectPath, const wxString &aHash, wxWindow *aParent=nullptr)
	Restore the project files to the state recorded by the given commit hash.

void	ShowRestoreDialog (const wxString &aProjectPath, wxWindow *aParent)
	Show a dialog allowing the user to choose a snapshot to restore.

void	WaitForPendingSave ()
	Block until any pending background save completes.

Private Member Functions
std::vector< LOCAL_HISTORY_SNAPSHOT_INFO >	LoadSnapshots (const wxString &aProjectPath)

bool	commitInBackground (const wxString &aProjectPath, const wxString &aTitle, const std::vector< HISTORY_FILE_DATA > &aFileData)
	Execute file writes and git commit on a background thread.

Private Attributes
std::set< wxString >	m_pendingFiles

std::map< const void *, std::function< void(const wxString &, std::vector< HISTORY_FILE_DATA > &)> >	m_savers

std::atomic< bool >	m_saveInProgress { false }

std::future< bool >	m_pendingFuture

Detailed Description

Simple local history manager built on libgit2.

Stores history for project files in a hidden .history git repository within the project directory.

Definition at line 73 of file local_history.h.

Constructor & Destructor Documentation

◆ LOCAL_HISTORY()

LOCAL_HISTORY::LOCAL_HISTORY ( )

Definition at line 199 of file local_history.cpp.

◆ ~LOCAL_HISTORY()

LOCAL_HISTORY::~LOCAL_HISTORY ( )

Definition at line 203 of file local_history.cpp.

References WaitForPendingSave().

Member Function Documentation

◆ ClearAllSavers()

void LOCAL_HISTORY::ClearAllSavers ( )

Clear all registered savers.

Definition at line 248 of file local_history.cpp.

References m_savers, traceAutoSave, and WaitForPendingSave().

Referenced by KIWAY::ProjectChanged().

◆ CommitDuplicateOfLastSave()

bool LOCAL_HISTORY::CommitDuplicateOfLastSave	(	const wxString &	aProjectPath,
		const wxString &	aFileType,
		const wxString &	aMessage )

Create a new commit duplicating the tree pointed to by Last_Save_<fileType> and move the Last_Save_<fileType> tag to the new commit (used when user discards changes).

Definition at line 1310 of file local_history.cpp.

References formatUsesIncrementalHistory(), HISTORY_LOCK_MANAGER::GetRepository(), HISTORY_LOCK_MANAGER::IsLocked(), isProjectDirectory(), Pgm(), and traceAutoSave.

Referenced by PCB_EDIT_FRAME::canCloseWindow(), and SCH_EDIT_FRAME::canCloseWindow().

◆ CommitFullProjectSnapshot()

bool LOCAL_HISTORY::CommitFullProjectSnapshot	(	const wxString &	aProjectPath,
		const wxString &	aTitle )

Commit a snapshot of the entire project directory (excluding the .history directory and ignored transient files) to the local history repository.

This does not modify any document dirty flags; it purely mirrors on-disk state for history purposes.

Definition at line 1173 of file local_history.cpp.

References collectProjectFiles(), commitSnapshotForProject(), formatUsesIncrementalHistory(), Init(), isProjectDirectory(), Pgm(), and traceAutoSave.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), KICAD_MANAGER_FRAME::CloseProject(), and KICAD_MANAGER_FRAME::LoadProject().

◆ commitInBackground()

bool LOCAL_HISTORY::commitInBackground	(	const wxString &	aProjectPath,
		const wxString &	aTitle,
		const std::vector< HISTORY_FILE_DATA > &	aFileData )

private

Execute file writes and git commit on a background thread.

Definition at line 584 of file local_history.cpp.

References PATHS::EnsurePathExists(), HISTORY_LOCK_MANAGER::GetIndex(), HISTORY_LOCK_MANAGER::GetLockError(), HISTORY_LOCK_MANAGER::GetRepository(), historyPath(), index, HISTORY_LOCK_MANAGER::IsLocked(), joinHistoryDestination(), KICAD_FORMAT::Prettify(), and traceAutoSave.

◆ CommitPending()

bool LOCAL_HISTORY::CommitPending ( )

Commit any pending modified files to the history repository.

Definition at line 837 of file local_history.cpp.

References CommitSnapshot(), and m_pendingFiles.

◆ CommitSnapshot()

bool LOCAL_HISTORY::CommitSnapshot	(	const std::vector< wxString > &	aFiles,
		const wxString &	aTitle )

Commit the given files to the local history repository.

Definition at line 1084 of file local_history.cpp.

References commitSnapshotForProject(), formatUsesIncrementalHistory(), Init(), isProjectDirectory(), and Pgm().

Referenced by CommitPending().

◆ EnforceSizeLimit()

bool LOCAL_HISTORY::EnforceSizeLimit	(	const wxString &	aProjectPath,
		size_t	aMaxBytes,
		PROGRESS_REPORTER *	aReporter = nullptr )

Enforce total size limit by rebuilding trimmed history keeping newest commits whose cumulative unique blob sizes fit within limit.

Definition at line 1565 of file local_history.cpp.

References _, PROGRESS_REPORTER::AdvancePhase(), compactRepository(), copyTreeObjects(), dirSizeRecursive(), HISTORY_LOCK_MANAGER::GetRepository(), historyPath(), HISTORY_LOCK_MANAGER::IsLocked(), name, HISTORY_LOCK_MANAGER::ReleaseRepository(), PROGRESS_REPORTER::Report(), PROGRESS_REPORTER::SetCurrentProgress(), and traceAutoSave.

Referenced by KICAD_MANAGER_FRAME::CloseProject().

◆ FindStaleAutosaveFiles()

std::vector< std::pair< wxString, wxString > > LOCAL_HISTORY::FindStaleAutosaveFiles ( const wxString & aProjectPath ) const

Enumerate autosave files newer than their corresponding source files for the project at aProjectPath.

Used by editors at startup to detect crash-recovery candidates.

Each entry in the returned vector has: first - autosave file path second - corresponding source path under the project directory

Definition at line 510 of file local_history.cpp.

References findAutosaveFilePairs().

Referenced by EDA_BASE_FRAME::CheckForAutosaveFiles().

◆ GetHeadHash()

wxString LOCAL_HISTORY::GetHeadHash ( const wxString & aProjectPath )

Return the current head commit hash.

Definition at line 1905 of file local_history.cpp.

References historyPath().

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), and KICAD_MANAGER_FRAME::LoadProject().

◆ HeadNewerThanLastSave()

bool LOCAL_HISTORY::HeadNewerThanLastSave ( const wxString & aProjectPath )

Return true if the autosave data is newer than the last manual save.

Definition at line 1255 of file local_history.cpp.

References historyPath().

◆ HistoryExists()

bool LOCAL_HISTORY::HistoryExists ( const wxString & aProjectPath )

Return true if history exists for the project.

Definition at line 1194 of file local_history.cpp.

References historyPath().

Referenced by KICAD_MANAGER_FRAME::doReCreateMenuBar(), and ShowRestoreDialog().

◆ Init()

bool LOCAL_HISTORY::Init ( const wxString & aProjectPath )

Initialize the local history repository for the given project path.

Definition at line 845 of file local_history.cpp.

References PATHS::EnsurePathExists(), formatUsesIncrementalHistory(), historyPath(), isProjectDirectory(), and Pgm().

Referenced by BOOST_AUTO_TEST_CASE(), CommitFullProjectSnapshot(), CommitSnapshot(), EDA_BASE_FRAME::CommonSettingsChanged(), PCB_EDIT_FRAME::OnBoardLoaded(), PCB_EDIT_FRAME::OpenProjectFiles(), SCH_EDIT_FRAME::OpenProjectFiles(), and RunRegisteredSaversAndCommit().

◆ LoadSnapshots()

std::vector< LOCAL_HISTORY_SNAPSHOT_INFO > LOCAL_HISTORY::LoadSnapshots ( const wxString & aProjectPath )

private

Definition at line 2676 of file local_history.cpp.

References historyPath(), and info.

Referenced by ShowRestoreDialog().

◆ NoteFileChange()

void LOCAL_HISTORY::NoteFileChange ( const wxString & aFile )

Record that a file has been modified and should be included in the next snapshot.

Definition at line 208 of file local_history.cpp.

References m_pendingFiles, and Pgm().

Referenced by PCB_EDIT_FRAME::OnModify(), and SCH_EDIT_FRAME::OnModify().

◆ RegisterSaver()

void LOCAL_HISTORY::RegisterSaver	(	const void *	aSaverObject,
		const std::function< void(const wxString &, std::vector< HISTORY_FILE_DATA > &)> &	aSaver )

Register a saver callback invoked during autosave history commits.

The callback receives the project path and should populate aFileData with serialized content or source paths for inclusion.

Parameters

aSaverObject	Unique object pointer identifier for this saver (to prevent duplicate registration)
aSaver	The saver callback function

Definition at line 219 of file local_history.cpp.

References m_savers, and traceAutoSave.

Referenced by BOOST_AUTO_TEST_CASE(), KICAD_MANAGER_FRAME::ProjectChanged(), PCB_EDIT_FRAME::ProjectChanged(), and SCH_EDIT_FRAME::ProjectChanged().

◆ RemoveAutosaveFiles() [1/2]

void LOCAL_HISTORY::RemoveAutosaveFiles ( const wxString & aProjectPath ) const

Remove every autosave file under the project at aProjectPath regardless of which source it shadowed.

Used when the user declines crash recovery so the stale set is not re-prompted next launch. Manual-save callers should prefer the source-scoped overload below to avoid wiping autosaves for files this save did not actually persist.

Definition at line 533 of file local_history.cpp.

References findAutosaveFilePairs().

Referenced by EDA_BASE_FRAME::CheckForAutosaveFiles(), KICAD_MANAGER_FRAME::CloseProject(), PCB_EDIT_FRAME::doCloseWindow(), SCH_EDIT_FRAME::doCloseWindow(), PCB_EDIT_FRAME::SavePcbFile(), and SCH_EDIT_FRAME::SaveProject().

◆ RemoveAutosaveFiles() [2/2]

void LOCAL_HISTORY::RemoveAutosaveFiles	(	const wxString &	aProjectPath,
		const std::vector< wxString > &	aSourcePaths ) const

Remove only the autosave files corresponding to aSourcePaths.

Called after a successful manual save so we drop autosaves the save just superseded without touching unsaved siblings (e.g. a PCB save must not erase a dirty schematic sheet's autosave when both editors are open).

Definition at line 546 of file local_history.cpp.

References findAutosaveFilePairs().

◆ RestoreCommit()

bool LOCAL_HISTORY::RestoreCommit	(	const wxString &	aProjectPath,
		const wxString &	aHash,
		wxWindow *	aParent = nullptr )

Restore the project files to the state recorded by the given commit hash.

Definition at line 2468 of file local_history.cpp.

References _, collectProjectFiles(), commitSnapshotWithLock(), Error, HISTORY_LOCK_MANAGER::GetIndex(), HISTORY_LOCK_MANAGER::GetRepository(), historyPath(), HISTORY_LOCK_MANAGER::IsLocked(), NoChanges, and traceAutoSave.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), KICAD_MANAGER_FRAME::LoadProject(), and ShowRestoreDialog().

◆ RunRegisteredSaversAndCommit()

bool LOCAL_HISTORY::RunRegisteredSaversAndCommit	(	const wxString &	aProjectPath,
		const wxString &	aTitle,
		const wxString &	aTagFileType = wxEmptyString )

Run all registered savers and, if any staged changes differ from HEAD, create a commit.

When aTagFileType is non-empty the new commit is tagged Save_<type>_N (manual save); empty leaves the commit untagged (autosave).

Definition at line 256 of file local_history.cpp.

References formatUsesIncrementalHistory(), Init(), isProjectDirectory(), m_saveInProgress, m_savers, Pgm(), traceAutoSave, and WaitForPendingSave().

Referenced by BOOST_AUTO_TEST_CASE(), EDA_BASE_FRAME::doAutoSave(), PCB_EDIT_FRAME::SavePcbFile(), and SCH_EDIT_FRAME::SaveProject().

◆ RunRegisteredSaversAsAutosaveFiles()

bool LOCAL_HISTORY::RunRegisteredSaversAsAutosaveFiles ( const wxString & aProjectPath )

Run all registered savers and write their output to autosave files instead of committing to the local history repository.

Used when BACKUP_FORMAT::ZIP is selected so the user still has crash recovery without a git store.

Output location follows BACKUP_LOCATION: PROJECT_DIR -> "<projectpath>/<reldir>/_autosave-<basename>" USER_DIR -> "<user_root>/<reldir>/<basename>" (mirroring the project tree)

Files are written via KIPLATFORM::IO::AtomicWriteFile so a crash mid-write cannot leave a half-written autosave on disk.

Definition at line 354 of file local_history.cpp.

References KIPLATFORM::IO::AtomicWriteFile(), PATHS::EnsurePathExists(), SETTINGS_MANAGER::GetAutosaveRootForProject(), SETTINGS_MANAGER::GetCommonSettings(), SETTINGS_MANAGER::GetProjectForPath(), PGM_BASE::GetSettingsManager(), COMMON_SETTINGS::AUTO_BACKUP::location, location, COMMON_SETTINGS::m_Backup, m_savers, Pgm(), KICAD_FORMAT::Prettify(), resolveAutosaveDestination(), and traceAutoSave.

Referenced by EDA_BASE_FRAME::doAutoSave().

◆ ShowRestoreDialog()

void LOCAL_HISTORY::ShowRestoreDialog	(	const wxString &	aProjectPath,
		wxWindow *	aParent )

Show a dialog allowing the user to choose a snapshot to restore.

Definition at line 2655 of file local_history.cpp.

References DIALOG_RESTORE_LOCAL_HISTORY::GetSelectedHash(), HistoryExists(), LoadSnapshots(), RestoreCommit(), and DIALOG_SHIM::ShowModal().

Referenced by KICAD_MANAGER_FRAME::RestoreLocalHistory().

◆ TagSave()

bool LOCAL_HISTORY::TagSave	(	const wxString &	aProjectPath,
		const wxString &	aFileType )

Tag a manual save in the local history repository.

Definition at line 1199 of file local_history.cpp.

References formatUsesIncrementalHistory(), HISTORY_LOCK_MANAGER::GetRepository(), HISTORY_LOCK_MANAGER::IsLocked(), isProjectDirectory(), Pgm(), and traceAutoSave.

Referenced by BOOST_AUTO_TEST_CASE(), KICAD_MANAGER_FRAME::CloseProject(), and KICAD_MANAGER_FRAME::LoadProject().

◆ UnregisterSaver()

void LOCAL_HISTORY::UnregisterSaver ( const void * aSaverObject )

Unregister a previously registered saver callback.

Parameters

aSaverObject The object pointer that was used to register the saver

Definition at line 234 of file local_history.cpp.

References m_savers, traceAutoSave, and WaitForPendingSave().

Referenced by BOOST_AUTO_TEST_CASE(), KICAD_MANAGER_FRAME::CloseProject(), PCB_EDIT_FRAME::doCloseWindow(), and SCH_EDIT_FRAME::doCloseWindow().

◆ WaitForPendingSave()

void LOCAL_HISTORY::WaitForPendingSave ( )

Block until any pending background save completes.

Call before reading repo state (HeadNewerThanLastSave / GetHeadHash) at close time so an in-flight autosave can't leave the close path with a stale view of HEAD.

Definition at line 827 of file local_history.cpp.

References m_pendingFuture, and traceAutoSave.

Referenced by ClearAllSavers(), KICAD_MANAGER_FRAME::CloseProject(), RunRegisteredSaversAndCommit(), UnregisterSaver(), and ~LOCAL_HISTORY().

Member Data Documentation

◆ m_pendingFiles

std::set<wxString> LOCAL_HISTORY::m_pendingFiles

private

Definition at line 203 of file local_history.h.

Referenced by CommitPending(), and NoteFileChange().

◆ m_pendingFuture

std::future<bool> LOCAL_HISTORY::m_pendingFuture

private

Definition at line 208 of file local_history.h.

Referenced by WaitForPendingSave().

◆ m_saveInProgress

std::atomic<bool> LOCAL_HISTORY::m_saveInProgress { false }

private

Definition at line 207 of file local_history.h.

Referenced by RunRegisteredSaversAndCommit().

◆ m_savers

std::map<const void*, std::function<void( const wxString&, std::vector<HISTORY_FILE_DATA>& )> > LOCAL_HISTORY::m_savers

private

Definition at line 205 of file local_history.h.

Referenced by ClearAllSavers(), RegisterSaver(), RunRegisteredSaversAndCommit(), RunRegisteredSaversAsAutosaveFiles(), and UnregisterSaver().

The documentation for this class was generated from the following files:

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ LOCAL_HISTORY()

◆ ~LOCAL_HISTORY()

Member Function Documentation

◆ ClearAllSavers()

◆ CommitDuplicateOfLastSave()

◆ CommitFullProjectSnapshot()

◆ commitInBackground()

◆ CommitPending()

◆ CommitSnapshot()

◆ EnforceSizeLimit()

◆ FindStaleAutosaveFiles()

◆ GetHeadHash()

◆ HeadNewerThanLastSave()

◆ HistoryExists()

◆ Init()

◆ LoadSnapshots()

◆ NoteFileChange()

◆ RegisterSaver()

◆ RemoveAutosaveFiles() [1/2]

◆ RemoveAutosaveFiles() [2/2]

◆ RestoreCommit()

◆ RunRegisteredSaversAndCommit()

◆ RunRegisteredSaversAsAutosaveFiles()

◆ ShowRestoreDialog()

◆ TagSave()

◆ UnregisterSaver()

◆ WaitForPendingSave()

Member Data Documentation

◆ m_pendingFiles

◆ m_pendingFuture

◆ m_saveInProgress

◆ m_savers