Skip to main content

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.
// From ghidra/framework/model/Project.java:26-48
public interface Project extends AutoCloseable, Iterable<DomainFile> {
    String getName();
    ProjectLocator getProjectLocator();
    ProjectData getProjectData();
    ToolManager getToolManager();
    ToolChest getLocalToolChest();
    RepositoryAdapter getRepository();
    void save();
    void close();
}

Project Structure

Physical Layout

A Ghidra project consists of several directories:
MyProject/
├── MyProject.gpr          # Project properties file
├── MyProject.rep/         # Project repository (if shared)
└── data/                  # Domain file storage
    ├── _projectState      # Project metadata
    ├── ~index.bak         # Index backup
    ├── ~index.dat         # File index
    └── [folders]/         # User-created folder hierarchy
        └── *.gbf          # Ghidra binary files (programs)

Domain Files

Domain files are the primary data artifacts in a project:
// From ghidra/framework/model/DomainFile.java
public interface DomainFile {
    String getName();
    String getPathname();
    DomainFolder getParent();
    boolean isCheckedOut();
    boolean isVersioned();
    int getLatestVersion();
    DomainObject getDomainObject(Object consumer, boolean okToUpgrade);
}
Common Domain File Types:

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
public RepositoryAdapter getRepository() {
    // Returns null for local projects
    // Returns RepositoryAdapter for shared projects
}
From ghidra/framework/model/Project.java:76-80

ProjectData Interface

The ProjectData interface provides access to the project’s file system:
// From ghidra/framework/model/ProjectData.java:30-38
public interface ProjectData extends Iterable<DomainFile> {
    DomainFolder getRootFolder();
    DomainFolder getFolder(String path);
    DomainFile getFile(String path);
    int getFileCount();
}

Folder Hierarchy

Projects organize files in a folder tree:
public interface DomainFolder {
    String getName();
    String getPathname();
    DomainFolder getParent();
    DomainFolder[] getFolders();
    DomainFile[] getFiles();
    DomainFolder createFolder(String name);
    DomainFile createFile(String name, DomainObject obj);
}
Use meaningful folder hierarchies to organize your analysis:
/firmware/
    /bootloader/
    /kernel/
    /drivers/
/malware/
    /samples/
    /unpacked/

Version Control

Shared projects provide full version control capabilities.

File Versioning

Each save creates a new version:
public interface DomainFile {
    boolean isVersioned();
    int getLatestVersion();
    Version[] getVersionHistory();
    DomainObject getReadOnlyVersion(int version, Object consumer);
    DomainObject getImmutableDomainObject(Object consumer, int version);
}
Version History:
public class Version {
    int getVersion();              // Version number
    long getCreateTime();          // Timestamp
    String getUser();              // Who created this version
    String getComment();           // Version comment
}

Check-Out Model

Shared projects use an exclusive check-out model:
1

Request Check-Out

User requests exclusive write access to a file
boolean checkout(boolean exclusive, TaskMonitor monitor);
2

Make Changes

User modifies the checked-out file locally
3

Check In

User commits changes back to the repository
void checkin(CheckinHandler handler, TaskMonitor monitor);
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:
public interface CheckinHandler {
    boolean keepCheckedOut();
    String getComment();
    boolean createKeepFile();
    boolean merge(DomainObject resultObj, DomainObject sourceObj);
}
Ghidra provides automatic and manual merge strategies:
  • Auto-merge - Combines non-conflicting changes
  • Manual merge - User resolves conflicts interactively
  • Keep file - Save pre-merge version as backup
From ghidra/framework/data/CheckinHandler.java

Project Views

Projects can include views of other projects:
// From ghidra/framework/model/Project.java:83-94
public ProjectData addProjectView(URL projectURL, boolean visible) 
        throws IOException {
    // Add read-only view of another project
}

public void removeProjectView(URL projectURL);

public ProjectLocator[] getProjectViews();
Use Cases:
  • 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:
public interface ToolManager {
    ToolTemplate[] getToolTemplates();
    PluginTool[] getRunningTools();
    Workspace getActiveWorkspace();
    PluginTool createTool(ToolTemplate template);
}
From ghidra/framework/model/ToolManager.java

Tool Templates

Templates define tool configurations:
public interface ToolTemplate {
    String getName();
    String getToolName();
    Set<String> getSupportedDataTypes();
    PluginInfo[] getPluginInfos();
}
Built-in Tools:
  • CodeBrowser - Primary analysis interface
  • VersionTracking - Compare program versions
  • FunctionGraphTool - Visualize control flow

Workspaces

Workspaces organize running tool windows:
public interface Workspace {
    String getName();
    ToolTemplate[] getToolTemplates();
    void save();
}

Storage Implementation

Understanding the storage layer helps with troubleshooting and administration.

File System Types

Indexed File System (Current):
  • Uses ~index.dat for fast lookups
  • Supports large projects efficiently
  • Required for file count queries
Mangled File System (Legacy):
  • Encodes paths in file names
  • Slower for large projects
  • No file count support
public interface ProjectData {
    Class<? extends LocalFileSystem> getLocalStorageClass();
    int getFileCount(); // Returns -1 for mangled file system
}
From ghidra/framework/model/ProjectData.java:40-96

Database Files

Domain files are stored as database files:
program.gbf/
├── ~index.dat         # Property index
├── program.gzf       # Compressed program data
└── user0.gvf         # User-specific data
Never manually modify files in the project directory. Always use Ghidra’s API or UI to manipulate domain files.

Project Lifecycle

Creating Projects

public interface ProjectManager {
    Project createProject(ProjectLocator projectLocator, 
                         RepositoryAdapter repository,
                         boolean remember);
    
    Project openProject(ProjectLocator projectLocator,
                       boolean doRestore,
                       boolean resetOwner);
}

Closing Projects

public void close() {
    // Saves project state
    // Closes all tools
    // Releases all domain objects
    // Disconnects from repository
}
From ghidra/framework/model/Project.java:108-111

Project Locking

Only one Ghidra instance can open a project at a time:
public class ProjectLock {
    // Prevents concurrent access
    // Lock file: [project].lock
}
From 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

public interface RepositoryAdapter {
    String getName();
    ServerInfo getServerInfo();
    User getUser();
    RepositoryItem[] getItemList(String folderPath);
    void connect() throws IOException;
    void disconnect();
}
From ghidra/framework/client/RepositoryAdapter.java

Best Practices

  • Use descriptive project names
  • Create folder hierarchies for related files
  • Separate projects by architecture or product
  • Archive completed analysis projects
  • Check in frequently with meaningful comments
  • Review version history before checking in
  • Resolve conflicts promptly
  • Use keep files for major changes
  • Communicate with team about check-outs
  • Establish naming conventions
  • Share data type archives
  • Document analysis decisions
  • Keep project file counts reasonable
  • Clean up unused files
  • Backup regularly
  • Monitor repository connection status

Troubleshooting

If project won’t open due to lock:
  1. Ensure no other Ghidra instances are running
  2. Check for zombie processes
  3. Manually remove .lock file (use caution)
If repository connection fails:
  • Verify server address and port
  • Check firewall settings
  • Confirm user credentials
  • Test network connectivity
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

Build docs developers (and LLMs) love