Project Fundamentals
A Ghidra project serves as a container for organizing reverse engineering work. Projects manage collections of domain files, tool configurations, and optional repository connections for collaboration.Project Structure
Physical Layout
A Ghidra project consists of several directories:Domain Files
Domain files are the primary data artifacts in a project:Program
Binary executables with analysis data (*.gzf)
Data Type Archive
Shared data type definitions (*.gdt)
Tool
Saved tool configurations (*.tool)
Folder Link
Links to external project folders
Project Types
Ghidra supports different project configurations:Local Projects
Standalone projects stored on the local file system:- No version control
- No collaboration features
- Fastest performance
- Ideal for personal analysis
Shared Projects
Projects connected to a Ghidra Server repository:- Version control for all files
- Multi-user collaboration
- Check-out/check-in workflow
- Merge conflict resolution
- User access control
ghidra/framework/model/Project.java:76-80
ProjectData Interface
TheProjectData interface provides access to the project’s file system:
Folder Hierarchy
Projects organize files in a folder tree:Version Control
Shared projects provide full version control capabilities.File Versioning
Each save creates a new version:Check-Out Model
Shared projects use an exclusive check-out model:
Check-Out States:
- Not Versioned - Local file, no repository
- Checked In - Latest version in repository
- Checked Out (Exclusive) - User has write lock
- Checked Out (Non-Exclusive) - Read-only checkout
- Hijacked - Local changes on checked-in file
Merging Changes
When checking in files that are out of date:- Auto-merge - Combines non-conflicting changes
- Manual merge - User resolves conflicts interactively
- Keep file - Save pre-merge version as backup
ghidra/framework/data/CheckinHandler.java
Project Views
Projects can include views of other projects:- Reference shared libraries across projects
- Access central data type archives
- Compare related programs
- Organize large analysis efforts
Project views are read-only. Changes must be made in the owning project.
Tool Management
Projects manage tool instances and configurations:ghidra/framework/model/ToolManager.java
Tool Templates
Templates define tool configurations:- CodeBrowser - Primary analysis interface
- VersionTracking - Compare program versions
- FunctionGraphTool - Visualize control flow
Workspaces
Workspaces organize running tool windows:Storage Implementation
Understanding the storage layer helps with troubleshooting and administration.File System Types
Indexed File System (Current):- Uses
~index.datfor fast lookups - Supports large projects efficiently
- Required for file count queries
- Encodes paths in file names
- Slower for large projects
- No file count support
ghidra/framework/model/ProjectData.java:40-96
Database Files
Domain files are stored as database files:Project Lifecycle
Creating Projects
Closing Projects
ghidra/framework/model/Project.java:108-111
Project Locking
Only one Ghidra instance can open a project at a time:ghidra/framework/data/ProjectLock.java
Repository Server
Shared projects connect to a Ghidra Server:Server Architecture
- Central Repository - Stores all versioned files
- User Management - Authentication and access control
- File Locking - Manages check-out/check-in
- Event Notification - Notifies clients of changes
Repository Adapter
ghidra/framework/client/RepositoryAdapter.java
Best Practices
Project Organization
Project Organization
- Use descriptive project names
- Create folder hierarchies for related files
- Separate projects by architecture or product
- Archive completed analysis projects
Version Control
Version Control
- Check in frequently with meaningful comments
- Review version history before checking in
- Resolve conflicts promptly
- Use keep files for major changes
Collaboration
Collaboration
- Communicate with team about check-outs
- Establish naming conventions
- Share data type archives
- Document analysis decisions
Performance
Performance
- Keep project file counts reasonable
- Clean up unused files
- Backup regularly
- Monitor repository connection status
Troubleshooting
Lock File Issues
Lock File Issues
If project won’t open due to lock:
- Ensure no other Ghidra instances are running
- Check for zombie processes
- Manually remove
.lockfile (use caution)
Repository Connection
Repository Connection
If repository connection fails:
- Verify server address and port
- Check firewall settings
- Confirm user credentials
- Test network connectivity
Merge Conflicts
Merge Conflicts
If merge fails:
- Create a keep file
- Manually merge in separate project
- Check in resolved version
Next Steps
Programs
Learn about the program model
Analysis
Understand analysis workflows
Architecture
Explore framework architecture
Overview
Return to framework overview
