Repository Management

The dbx clone, dbx sync, dbx swap, dbx branch, dbx switch, dbx log, and dbx open commands provide repository management functionality for cloning and managing groups of related repositories.

Initialize Configuration

Before using the repo commands, initialize your configuration file:

# Create user configuration file at ~/.config/dbx-python-cli/config.toml
dbx config init

This creates a configuration file with default repository groups that you can customize.

Clone Repositories by Group

Clone repositories from predefined groups:

# Clone pymongo repositories
dbx clone -g pymongo

# Clone langchain repositories
dbx clone -g langchain

# Clone django repositories
dbx clone -g django

# Clone all groups from configuration
dbx clone -a
# or
dbx clone --all

Fork-Based Workflow

For contributing to upstream repositories, you can clone from your personal fork and automatically set up the upstream remote:

# Clone from your GitHub fork instead of the upstream org
dbx clone -g pymongo --fork-user aclark4life

This will:

  1. Clone from git@github.com:aclark4life/mongo-python-driver.git (your fork)

  2. Add an upstream remote pointing to git@github.com:mongodb/mongo-python-driver.git (original repo)

  3. Set up your local repository ready for the fork-based contribution workflow

Because mongo-python-driver is a global repo it is cloned into the target group directory (e.g. pymongo/mongo-python-driver when you clone the pymongo group).

Example workflow:

# Clone your forks with upstream remotes configured
# mongo-python-driver (global) is also cloned into pymongo/
dbx clone -g pymongo --fork-user aclark4life

# Now you can work with the standard fork workflow
cd ~/Developer/mongodb/pymongo/mongo-python-driver
git remote -v
# origin    git@github.com:aclark4life/mongo-python-driver.git (fetch)
# origin    git@github.com:aclark4life/mongo-python-driver.git (push)
# upstream  git@github.com:mongodb/mongo-python-driver.git (fetch)
# upstream  git@github.com:mongodb/mongo-python-driver.git (push)

# Fetch latest changes from upstream
git fetch upstream
git merge upstream/main

Configuration:

You can optionally set a default fork username in your configuration file to avoid typing it every time:

[repo]
base_dir = "~/Developer/mongodb"
# fork_user = "your-github-username"  # Optional: specify your GitHub username for fork operations

[repo.groups.pymongo]
repos = [
    "git@github.com:mongodb/mongo-python-driver.git",
]

With this configuration, you can simply run:

# Uses fork_user from config
dbx clone -g pymongo --fork

# Or specify a different username
dbx clone -g pymongo --fork-user different-user

Clone All Groups

You can clone all groups defined in your configuration at once using the -a or --all flag:

# Clone all groups from configuration
dbx clone -a

# Clone all groups with fork workflow
dbx clone -a --fork-user aclark4life

# Clone all groups without automatic installation
dbx clone -a --no-install

This will:

  1. Clone all repositories from every non-global group defined in your configuration

  2. Create separate directories for each non-global group under your base_dir

  3. Automatically include global group repositories in each non-global group

  4. Optionally install dependencies if --no-install is not specified

Example:

If your configuration has groups global, pymongo, django, and langchain, running dbx clone -a will:

  • Clone pymongo group repos (plus global repos) into ~/Developer/mongodb/pymongo/

  • Clone django group repos (plus global repos) into ~/Developer/mongodb/django/

  • Clone langchain group repos (plus global repos) into ~/Developer/mongodb/langchain/

Note that the global group itself does not get its own directory - its repositories are only cloned into the other group directories.

This is useful when setting up a new development environment or when you want to work with all configured repositories.

Sync Fork with Upstream

After cloning with the fork workflow, you can easily sync your local repository with upstream changes:

# Sync a specific repository
dbx sync mongo-python-driver

# Sync all repositories in a group
dbx sync -g pymongo

# Sync all repositories across all groups
dbx sync -a

# Preview what would be synced without making changes
dbx sync mongo-python-driver --dry-run

# Force push after rebasing (use if previous sync failed to push)
dbx sync mongo-python-driver --force

# List available repositories
dbx sync -l

This command will:

  1. Fetch the latest changes from the upstream remote

  2. Rebase your current branch on top of upstream/<current-branch>

  3. Push the rebased branch to origin (your fork)

  4. If --force is used, force push with --force-with-lease for safety

  5. If --dry-run is used, compare commits between upstream and origin without making changes

Example workflow:

# Clone your fork with upstream configured
dbx clone -g pymongo --fork-user aclark4life

# Make some changes in your fork
cd ~/Developer/mongodb/pymongo/mongo-python-driver
git checkout -b my-feature
# ... make changes ...
git commit -am "Add new feature"

# Preview what would be synced (dry run)
dbx sync mongo-python-driver --dry-run
# Shows commits that would be applied from upstream and commits that would be rebased

# Sync with upstream to get latest changes and push
dbx sync mongo-python-driver
# Fetches from upstream, rebases your branch, and pushes to origin

# Your changes are now in your fork, ready for a pull request!

Notes:

  • The sync command requires an upstream remote to be configured

  • If you cloned with --fork, the upstream remote is automatically set up

  • The command will rebase your current branch on upstream/<current-branch>

  • After rebasing, it automatically pushes to origin/<current-branch>

  • If the push fails (e.g., you’ve already pushed and rebased), use --force flag

  • The --force flag uses --force-with-lease for safety (won’t overwrite others’ changes)

  • If there are rebase conflicts, you’ll need to resolve them manually

  • Works with any repository that has an upstream remote, not just forks

Swap Origin and Upstream

After setting up a fork workflow, you may occasionally need to swap your origin and upstream remotes — for example, if you initially cloned the upstream repo directly and later created a fork.

# Swap remotes for a specific repository
dbx swap mongo-python-driver

# Swap by navigating to the repo directory
cd ~/Developer/mongodb/pymongo/mongo-python-driver
dbx swap .

# Swap all repositories in a group
dbx swap -g pymongo

# Preview what would change without making modifications
dbx swap mongo-python-driver --dry-run
dbx swap -g pymongo --dry-run

After swapping, what was origin becomes upstream and vice versa. This is useful when:

  • You cloned a repo directly and then forked it — swap so your fork is origin

  • You want to point origin back to the canonical repo and upstream to your fork

Notes:

  • Both origin and upstream remotes must already be configured; the command will fail if either is missing

  • Use --dry-run first to verify the swap looks correct before applying it

Available Groups (Default):

  • global - Reserved for repos shared across all groups (currently empty)

  • pymongo - MongoDB Python driver and related repositories

  • langchain - LangChain framework repositories

  • django - Django and MongoDB backend repositories

  • django-thirdparty - Third-party Django packages

  • ci - CI tooling (drivers-evergreen-tools, drivers-github-tools, mongo-orchestration, ai-ml-pipeline-testing)

  • wagtail - Wagtail CMS repositories

  • demo - Demo applications

Global Groups

A global group is a special group whose repositories are automatically cloned into every other group when you run dbx clone -g <group>. This is useful for repos that every group needs — for example, the MongoDB Python driver is a shared dependency for all driver-related groups.

# Clones django repos AND mongo-python-driver into ~/Developer/mongodb/django/
dbx clone -g django

# Clones pymongo repos AND mongo-python-driver into ~/Developer/mongodb/pymongo/
dbx clone -g pymongo

Global groups are declared with global_groups under [repo]:

[repo]
base_dir = "~/Developer/mongodb"
global_groups = ["global"]  # these repos are injected into every group clone

[repo.groups.global]
repos = [
    "git@github.com:your-org/shared-tools.git",
]

[repo.groups.pymongo]
repos = [
    "git@github.com:mongodb/mongo-python-driver.git",
    "git@github.com:mongodb/specifications.git",
]

Because repos in the global group end up physically inside each target group directory, dbx install -g pymongo and dbx test shared-tools all work without any extra flags.

Flat Layout

By default dbx uses a two-level directory layout (base_dir/<group>/<repo>). Setting flat = true collapses this so all repositories live directly under base_dir:

[repo]
base_dir = "~/Developer/mongodb"
flat = true

[repo.groups.pymongo]
repos = [
    "git@github.com:mongodb/mongo-python-driver.git",
    "git@github.com:mongodb/specifications.git",
]

[repo.groups.django]
repos = [
    "git@github.com:mongodb-labs/django-mongodb-backend.git",
]

Resulting layout:

~/Developer/mongodb/
├── mongo-python-driver/
├── specifications/
└── django-mongodb-backend/

In flat mode:

  • Group membership is resolved from the config rather than directory structure.

  • dbx list shows a tree grouped by config group (same visual style as grouped mode).

  • dbx clone -g pymongo clones directly into base_dir instead of base_dir/pymongo/.

  • A single shared .venv is used across all groups.

  • All other commands (-g, install, test, etc.) continue to work normally.

Configuration:

Repository groups are defined in ~/.config/dbx-python-cli/config.toml. The default base directory for cloning is ~/Developer/dbx-repos, which can be customized.

Repositories are cloned into subdirectories named after their group. For example, the pymongo group will be cloned to ~/Developer/dbx-repos/pymongo/.

[repo]
base_dir = "~/Developer/dbx-repos"
global_groups = ["global"]

[repo.groups.global]
repos = [
    "https://github.com/mongodb/mongo-python-driver.git",
]

[repo.groups.pymongo]
repos = [
    "https://github.com/mongodb/specifications.git",
]

[repo.groups.django]
repos = [
    "https://github.com/django/django.git",
    "https://github.com/mongodb-labs/django-mongodb-backend.git",
]

[repo.groups.custom]
repos = [
    "https://github.com/your-org/your-repo.git",
]

You can add your own custom groups by editing the configuration file.

Features:

  • User-specific configuration file (works with pip-installed package)

  • Clones all repositories in a group to the configured base directory

  • Skips repositories that already exist locally

  • Fork-based workflow support with automatic upstream remote configuration

  • Sync command to fetch from upstream and rebase current branch

  • Provides clear progress feedback with emoji indicators

  • Handles errors gracefully and continues with remaining repositories

  • Easy to add custom repository groups

View Git Branches

The dbx branch command allows you to run git branch in one or more repositories:

# Show branches in a single repository
dbx branch mongo-python-driver

# Show all branches (including remote branches)
dbx branch mongo-python-driver -a

# Show branches with verbose information
dbx branch mongo-python-driver -v

# Show branches in all repositories in a group
dbx branch -g pymongo

# Show branches in all repositories in a group with arguments
dbx branch -g pymongo -a

# Show branches in a project
dbx branch -p myproject

This command will:

  1. Find the repository, group, or project by name

  2. Run git branch with any provided arguments

  3. Display the output for each repository

Examples:

# View local branches in a single repo
$ dbx branch mongo-python-driver
🌿 mongo-python-driver:
* main
  feature-branch

# View all branches (local and remote)
$ dbx branch mongo-python-driver -a
🌿 mongo-python-driver: git branch -a
* main
  feature-branch
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/feature-branch

# View branches across all repos in a group
$ dbx branch -g pymongo
Running git branch in 2 repository(ies) in group 'pymongo':

🌿 mongo-python-driver:
* main
🌿 specifications:
* master

# View all branches (local and remote) across all repos in a group
$ dbx branch -g pymongo -a
Running git branch in 2 repository(ies) in group 'pymongo':

🌿 mongo-python-driver: git branch -a
* main
  feature-branch
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/feature-branch
🌿 specifications: git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

Notes:

  • The command works with any repository that has been cloned using dbx clone

  • You can pass any valid git branch arguments (e.g., -a, -r, -v, --merged)

  • The -a or --all flag shows all branches (local and remote) for all repositories

  • When using with a group, the command runs in all repositories in that group

  • Projects without a .git directory will be skipped with a warning

  • Run dbx list to see all available repositories

Switch Git Branches

The dbx switch command allows you to switch git branches in one or more repositories:

# Switch to a branch in a single repository
dbx switch mongo-python-driver PYTHON-5683

# Switch branches in all repositories in a group
dbx switch -g pymongo main

# Switch branches in a project
dbx switch -p myproject feature-branch

# Create and switch to a new branch
dbx switch mongo-python-driver new-feature --create

# List available repositories
dbx switch --list

This command will:

  1. Find the repository, group, or project by name

  2. Run git switch <branch> to switch to the specified branch

  3. Optionally create the branch if --create flag is used

  4. Display the output for each repository

Examples:

# Switch to an existing branch
$ dbx switch mongo-python-driver PYTHON-5683
🔀 mongo-python-driver: Switched to branch 'PYTHON-5683'

# Create and switch to a new branch
$ dbx switch mongo-python-driver new-feature --create
🔀 mongo-python-driver: Switched to a new branch 'new-feature'

# Switch all repos in a group to main branch
$ dbx switch -g pymongo main
Switching to branch 'main' in 2 repository(ies) in group 'pymongo':

🔀 mongo-python-driver: Switched to branch 'main'
🔀 specifications: Switched to branch 'main'

Notes:

  • The command works with any repository that has been cloned using dbx clone

  • When using with a group, the command runs in all repositories in that group

  • The --create flag creates a new branch if it doesn’t exist

  • Projects without a .git directory will be skipped with a warning

  • Run dbx list to see all available repositories

View Git Commit Logs

The dbx log command allows you to view git commit logs from one or more repositories:

# Show last 10 commits from a repository
dbx log mongo-python-driver

# Show last 20 commits
dbx log -n 20 mongo-python-driver

# Show logs in oneline format
dbx log --oneline mongo-python-driver

# Show logs from all repositories in a group
dbx log -g pymongo

# Show last 5 commits from all repos in a group
dbx log -n 5 -g pymongo

# Show logs from a project
dbx log -p myproject

This command will:

  1. Find the repository, group, or project by name

  2. Run git log with the specified options

  3. Display the commit logs for each repository

Examples:

# View last 10 commits (default)
$ dbx log mongo-python-driver
📜 mongo-python-driver: Last 10 commits
commit abc123...
Author: John Doe <john@example.com>
Date:   Mon Jan 1 12:00:00 2024 -0500

    Add new feature

# View last 5 commits in oneline format
$ dbx log -n 5 --oneline mongo-python-driver
📜 mongo-python-driver: Last 5 commits (oneline)
abc123 Add new feature
def456 Fix bug
ghi789 Update docs

# View logs from all repos in a group
$ dbx log -g pymongo
📜 mongo-python-driver: Last 10 commits
...
📜 specifications: Last 10 commits
...

Notes:

  • The command works with any repository that has been cloned using dbx clone

  • Default number of commits shown is 10

  • Use -n or --number to specify a custom number of commits

  • Use --oneline for a compact one-line-per-commit format

  • When using with a group, the command runs in all repositories in that group

  • Projects without a .git directory will be skipped with a warning

  • Run dbx list to see all available repositories

Open Repositories in Browser

The dbx open command allows you to open repositories in your web browser:

# Open a single repository in browser
dbx open mongo-python-driver

# Open all repositories in a group
dbx open -g pymongo

This command will:

  1. Find the repository or group by name

  2. Get the git remote URL from the repository

  3. Convert the git URL to a browser-friendly URL

  4. Open the URL in your default web browser

Examples:

# Open a single repository
$ dbx open mongo-python-driver
🌐 Opening mongo-python-driver in browser...
# Opens https://github.com/mongodb/mongo-python-driver

# Open all repos in a group
$ dbx open -g pymongo
Opening 2 repository(ies) in group 'pymongo' in browser:

🌐 Opening mongo-python-driver in browser...
🌐 Opening specifications in browser...

Notes:

  • The command works with any repository that has been cloned using dbx clone

  • Automatically converts SSH URLs (git@github.com:org/repo.git) to HTTPS URLs (https://github.com/org/repo)

  • Also works with HTTPS git URLs

  • When using with a group, opens all repositories in that group

  • Requires the repository to have an origin remote configured

  • Run dbx list to see all available repositories