bitp 1.1.0

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

# Create a new Yocto project
bit create -b scarthgap --execute
bit setup

# Check status of all layer repos
bit status

# Interactively explore repos and commits
bit explore

# Update all repos (interactive)
bit update

# Update all repos non-interactively (apply saved defaults)
bit update -y

# Search for layers in the OE Layer Index
bit layer-index 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
info	i	Show build configuration and layer status
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
create	-	Create a new Yocto/OE project (clone core repos)
setup	-	Show OE/Yocto build environment setup command
setup shell	-	Start shell with OE build environment pre-sourced
layer-index	-	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

# Create project and clone core repos
bit create -b scarthgap --execute

# Get the environment setup command
bit setup

# 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

# Update all repos non-interactively (apply saved defaults)
bit update -y

# 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
• B - switch all repos to branch (common branches first, partial dimmed)
• t - launch git history viewer (tig/lazygit/gitk)
• v - toggle verbose display (HEAD commit per repo/layer)
• \ - 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 (stat ↔ full patch)
• a - toggle blame view in preview
• f - switch to file/tree view (browse files, expand commit history per file)
• c - copy commit hash
• e - export selected commits
• i - interactive rebase (select range, then squash/reword/reorder)
• t - launch git history viewer
• l - filter upstream commits by layer (multi-layer repos)
• PgUp/PgDn - scroll commit list
• Alt-Up/Alt-Down - scroll preview page
• Ctrl-U/Ctrl-D - scroll preview half-page
• ← or b - go back
• q - quit

Keybindings in file/tree view (f from commit browser):

• Enter/→ - expand directory or show file's commit history
• ← - collapse directory/file or go to parent
• \ - toggle expand/collapse directory or file commits
• d - toggle diff view in preview
• a - toggle blame view
• f - toggle raw file content view
• ? - toggle preview pane
• b/Esc - go back to commit browser
• 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 layer-index

# Search with query
bit layer-index virtualization

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

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

Managing Branches

# Interactive branch management
bit branch

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

Keybindings in branch management (bit branch):

• Enter/→ - expand repo to show branches / switch to selected branch
• ← - collapse expanded repo
• B - switch all repos to branch (common branches first, partial dimmed)
• q - quit

Viewing Build Info

# Show build configuration (like BitBake summary)
bit info

# Show only layer info with branch:commit
bit info layers

# Show only key variables
bit info vars

Output format matches BitBake's build configuration:

Build Configuration:
  MACHINE = qemuarm64
  DISTRO  = poky

Layers:
  meta                = "master:01a65e8d5f73..."
  meta-selftest
  meta-poky           = "master:de4abc0a175a..."

The info entry is also available in the explore repo list menu for interactive browsing.

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:

• Mode - Color source: global (~/.config/bit/colors.json), per-project (.bit.defaults), or built-in defaults
• Theme - Base color scheme (default, dark, light, dracula, nord, etc.)
• Individual - Per-element color overrides with live preview

New projects default to global mode — changing colors in any project updates ~/.config/bit/colors.json, shared by all projects in global mode. Switch to custom for per-project overrides.

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 upstream tracking ref
• ↓ 3 - commits to pull from upstream
• → contrib - tracking a non-origin remote (shown when not tracking origin)
• [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
│   ├── test_info.py              # Info command parsing and formatting
│   └── test_update.py            # Update command (upstream tracking)
├── 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
    ├── info.py       # info command (build configuration)
    ├── update.py     # update command (upstream tracking support)
    ├── search.py     # layer-index command
    ├── setup.py      # create, setup 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