bitp 1.0.9

Tools for BitBake/Yocto projects

bitp

A CLI tool for managing BitBake/Yocto/OpenEmbedded layer repositories.

The command is bit for quick typing.

Overview

bit helps developers working with Yocto/OpenEmbedded projects by providing tools to:

• Update git repos backing BitBake layers from a bblayers.conf
• Explore commits interactively with fzf-based navigation
• Export patches with cover letters for upstream submission
• Manage branches across multiple layer repositories
• Search the OpenEmbedded Layer Index for layers
• Bootstrap new projects by cloning core repositories
• Manage projects - switch between multiple Yocto builds from anywhere

Features

• Automatic layer discovery - finds layers by searching for conf/layer.conf files
• Multi-layer repo support - handles repos containing multiple layers (e.g., meta-openembedded)
• Interactive fzf menus - fast navigation with preview panes and keyboard shortcuts
• Tab completion - bash completion via argcomplete
• Background refresh - upstream status checks run in background for fast startup
• Per-repo configuration - custom display names, update defaults, push targets

Quick Start

# Bootstrap a new Yocto project
bit init clone -b scarthgap --execute
bit init

# Check status of all layer repos
bit status

# Interactively explore repos and commits
bit explore

# Update all repos
bit update

# Search for layers in the OE Layer Index
bit search security

Commands

Command	Alias	Description
explore	x	Interactively explore commits in layer repos
update	u	Update git repos referenced by layers
status	-	Show local commit summary for layer repos
config	c	View and configure repo/layer settings
branch	b	View and switch branches across repos
export	-	Export patches from layer repos
repos	-	List layer repos
init	-	Show OE/Yocto build environment setup command
init clone	-	Show or clone core Yocto/OE repositories
search	-	Search OpenEmbedded Layer Index for layers
projects	p	Manage and switch between multiple project directories

Run bit with no arguments for an interactive command menu, or bit --help for detailed usage.

Common Workflows

Starting a New Project

# Clone core repos
bit init clone -b scarthgap --execute

# Get the environment setup command
bit init

# Source the environment (copy from output above)
TEMPLATECONF=... source ./layers/openembedded-core/oe-init-build-env

Daily Development

# Check what's changed upstream
bit status

# Update repos (interactive)
bit update

# Or update a specific repo
bit update OE-core

Exploring Commits

# Interactive two-level browser
bit explore

# Jump directly to a repo
bit x OE-core

Keybindings in explore mode (repo list):

• Enter - explore commits in selected repo
• u - pull --rebase
• m - pull (merge)
• r - refresh repo (fetch)
• R - refresh all repos
• t - launch git history viewer (tig/lazygit/gitk)
• s - show repo status detail
• v - toggle verbose display
• \ - expand/collapse all multi-layer repos
• c - open config menu
• q - quit

Keybindings in commit browser:

• Tab - mark commit for selection
• Space - select range of commits
• ? - toggle preview pane
• d - toggle diff view in preview
• c - copy commit hash
• e - export selected commits
• t - launch git history viewer
• ← or b - go back
• q - quit

Exporting Patches for Upstream

# Prepare commits (reorder for upstream)
bit export prep --branch zedd/feature

# Export patches
bit export --target-dir ~/patches

# Export with version number
bit export --target-dir ~/patches -v 2

Searching for Layers

# Interactive search
bit search

# Search with query
bit search virtualization

# Get layer info for scripting
bit search -i meta-virtualization

# Clone a layer directly
bit search -c meta-security -b scarthgap

Managing Branches

# Interactive branch management
bit branch

# Switch all repos to a release branch
bit branch --all scarthgap

Managing Multiple Projects

# Open project manager (interactive)
bit projects

# Add a project directory
bit projects add /path/to/yocto-build

# List known projects
bit projects list

# Remove a project from tracking
bit projects remove /path/to/old-project

Keybindings in projects menu:

• Space - activate selected project (all commands will operate on it)
• Enter - activate project and open command menu (if auto-invoked)
• + - browse for a new directory to add
• - - remove selected project from tracking
• c - clear active project (use current directory)
• s - open settings

Note: When no valid project context exists (no bblayers.conf found), the projects picker is automatically shown.

Configuration

Per-repo settings are stored in .bit.defaults (JSON):

{
  "/path/to/poky": "rebase",
  "/path/to/meta-oe": "skip",
  "__extra_repos__": ["/path/to/bitbake"],
  "__hidden_repos__": ["/path/to/unwanted-repo"],
  "__push_targets__": {
    "/path/to/oe-core": {
      "push_url": "ssh://[e-mail]/oe-core-contrib",
      "branch_prefix": "yourname/"
    }
  },
  "fzf_theme": "dark",
  "fzf_text_color": "light-gray",
  "fzf_custom_colors": {"pointer": "green"}
}

Configure interactively with bit config.

Theme Customization

The tool supports customizable options via Settings menu (bit config -> Settings):

Colors submenu:

• Theme - Base color scheme (default, dark, light, dracula, nord, etc.)
• Individual - Per-element color overrides with live preview

A color preview panel shows all themed elements (pointer, header, prompt, etc.) with current colors applied.

Directory Browser - Choose preferred file browser for project selection:

• broot (recommended)
• ranger
• nnn
• fzf (fallback)

Git Viewer - Choose preferred git history viewer:

• auto (detect first available: tig > lazygit > gitk)
• tig - ncurses git interface
• lazygit - terminal UI for git
• gitk - graphical git browser

Preview Layout - Configure commit browser preview pane position:

• Bottom (default) - preview below commit list
• Right (side-by-side) - preview beside commit list
• Top - preview above commit list

Terminal Colors - Configure output colors for:

• Upstream indicator (commits to pull)
• Local commit count
• Dirty/clean status
• Repo names (configured, discovered, external)

Visual Indicators

Repos are color-coded by source:

• Green - from bblayers.conf
• Magenta with (?) - discovered layers (not in bblayers.conf)
• Cyan with (ext) - external repos (git repos without conf/layer.conf)

Status indicators:

• 5 local - commits ahead of origin
• ↓ 3 - commits to pull from upstream
• [clean] / [DIRTY] - working tree status

Requirements

• Python 3.9+
• Git
• fzf (optional, but recommended for interactive features)
• argcomplete (optional, for tab completion)
• xclip or xsel (optional, for clipboard support)

Development

Installation for Development

# Clone the repository
git clone https://gitlab.com/bruce-ashfield/bitbake-project.git
cd bitbake-project

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e .[dev]

Running Tests

The project uses pytest with pytest-mock and pytest-cov:

# Activate virtual environment first
source .venv/bin/activate

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ --cov=bitbake_project --cov-report=term-missing

# Run only unit tests
pytest tests/unit/ -v

# Run only integration tests
pytest tests/integration/ -v

# Run tests matching a pattern
pytest tests/ -k "test_colors" -v

Test Structure

tests/
├── conftest.py                    # Shared fixtures
├── unit/
│   ├── test_colors.py            # Colors class ANSI formatting
│   ├── test_helpers.py           # Pure functions (clean_title, dedupe, sort)
│   ├── test_state.py             # State management (defaults, prep, export)
│   ├── test_gitrepo.py           # GitRepo class
│   ├── test_fzf_menu.py          # FzfMenu class (mocked)
│   ├── test_bblayers_parser.py   # BblayersParser
│   └── test_cli_parser.py        # CLI argument parsing
├── integration/
│   ├── test_cli_dispatch.py      # Command dispatch, --help, aliases
│   └── test_projects_command.py  # Projects add/remove/list
└── data/
    └── bblayers/                  # Test bblayers.conf files

Project Structure

The project is organized as a Python package with a commands subpackage:

bitbake_project/
├── core.py           # Core abstractions (Colors, GitRepo, FzfMenu)
├── cli.py            # Argument parsing and main()
└── commands/         # Command implementations
    ├── common.py     # Shared utilities (BblayersParser, etc.)
    ├── explore.py    # explore, status commands
    ├── export.py     # export, export prep commands
    ├── config.py     # config command
    ├── branch.py     # branch command
    ├── update.py     # update command
    ├── search.py     # search command
    ├── init.py       # init, bootstrap commands
    ├── repos.py      # repos command
    └── projects.py   # projects command, directory browser

Distribution options:

• Standalone: Single-file zipapp (dist/bit)
• Pip install: pip install -e . for development

License

This project is licensed under the GNU General Public License v2.0 (GPL-2.0-only).

See COPYING for the full license text.

See Also

• INSTALL.md - Installation instructions
• Yocto Project
• OpenEmbedded
• OpenEmbedded Layer Index