The Ultimate Bitbucket Cheat Sheet: Complete Git Workflow Guide

Introduction

Bitbucket is a Git-based code hosting and collaboration platform developed by Atlassian. It provides version control, enables team collaboration, and integrates with other Atlassian products like Jira and Confluence. This cheat sheet covers essential commands and workflows for effectively using Bitbucket, from basic repository management to advanced CI/CD integration.

Core Concepts

Bitbucket Architecture

• Repository: Storage location for your project’s code
• Branch: Independent line of development
• Pull Request (PR): Request to merge changes from one branch to another
• Pipeline: CI/CD workflow defined in Bitbucket
• Workspace: Organization unit that contains repositories and users
• Project: Collection of repositories that belong together

Access Control Levels

• Admin: Full control of repository and settings
• Write: Push code and create branches
• Read: View and clone repository
• No access: Cannot view repository

Setting Up Bitbucket

Account Setup

1. Create a Bitbucket account at bitbucket.org
2. Set up SSH keys (Account → Settings → SSH Keys)
3. Configure two-factor authentication for security

Repository Creation

# Create a new local repository and push to Bitbucket
git init
git add .
git commit -m "Initial commit"
git remote add origin https://bitbucket.org/username/repo.git
git push -u origin master

# Clone an existing Bitbucket repository
git clone https://bitbucket.org/username/repo.git
# Or using SSH
git clone git@bitbucket.org:username/repo.git

Basic Git Commands for Bitbucket

Daily Workflow Commands

# Update your local repository
git pull origin branch-name

# Create and switch to a new branch
git checkout -b new-branch-name

# Stage modified files
git add filename    # Stage specific file
git add .           # Stage all files

# Commit changes
git commit -m "Commit message"

# Push to Bitbucket
git push origin branch-name

Branch Management

# List all branches
git branch -a

# Switch to an existing branch
git checkout branch-name

# Delete a local branch
git branch -d branch-name

# Delete a remote branch
git push origin --delete branch-name

# Rename current branch
git branch -m new-branch-name

Pull Requests and Code Review

Creating Pull Requests

1. Push your branch to Bitbucket: git push origin feature-branch
2. Navigate to your repository on Bitbucket
3. Click “Create pull request”
4. Select source branch (your feature branch) and destination branch (usually main/master)
5. Add title, description, and reviewers
6. Click “Create”

PR Best Practices

• Keep PRs small and focused on a single issue/feature
• Write clear PR descriptions with context and testing steps
• Link related Jira issues in the PR description
• Request reviews from appropriate team members
• Address all comments before merging

Code Review Commands

# Get the latest changes from a PR to review locally
git fetch origin
git checkout pull-request-branch

# Create a local branch to review a specific PR (#123)
git fetch origin pull/123/head:review-branch-name
git checkout review-branch-name

Bitbucket-Specific Features

Repository Settings

• Branching model: Configure branch permissions and workflows
• Merge strategies: Choose between merge commit, squash, or fast-forward
• Branch restrictions: Limit who can push to specific branches
• Default reviewers: Automatically assign reviewers to PRs

Bitbucket Pipelines

pipeline.yml Structure

pipelines:
  default:
    - step:
        name: Build and test
        image: node:14
        script:
          - npm install
          - npm test
        artifacts:
          - dist/**
  branches:
    master:
      - step:
          name: Deploy to production
          deployment: production
          script:
            - npm install
            - npm run build
            - pipe: atlassian/aws-s3-deploy:0.4.0
              variables:
                AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
                AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
                AWS_DEFAULT_REGION: $AWS_DEFAULT_REGION
                S3_BUCKET: $S3_BUCKET
                LOCAL_PATH: 'dist'

Common Pipeline Tasks

• Running tests
• Building applications
• Deploying to environments
• Code quality checks
• Sending notifications

Working with Jira Integration

Linking Commits to Jira Issues

# Include Jira issue key in commit message
git commit -m "ABC-123 Fix login bug"

# Multiple issues
git commit -m "ABC-123, DEF-456 Update dependencies"

Smart Commits

# Transition issue to "In Progress"
git commit -m "ABC-123 #in-progress Working on login fix"

# Add a comment to the issue
git commit -m "ABC-123 #comment Fixed null pointer exception"

# Log time spent
git commit -m "ABC-123 #time 2h Fixed rendering issue"

# Resolve issue
git commit -m "ABC-123 #resolve Fixed login bug"

Comparison: Git Hosting Platforms

Common Challenges and Solutions

Challenge: Merge Conflicts

Solution:

# Pull latest changes from target branch
git checkout master
git pull

# Rebase your branch
git checkout feature-branch
git rebase master

# Resolve conflicts in each file
# After resolving, continue the rebase
git add .
git rebase --continue

# Push your changes (force required after rebase)
git push origin feature-branch --force-with-lease

Challenge: Accidentally Committed to Wrong Branch

Solution:

# First, save your changes
git log -n 1  # Note the commit hash
git checkout correct-branch
git cherry-pick commit-hash
git checkout wrong-branch
git reset --hard HEAD~1  # Remove commit from wrong branch
git push origin correct-branch
git push origin wrong-branch --force-with-lease

Challenge: Pipeline Failures

Solutions:

• Check pipeline logs for specific errors
• Test pipeline locally using Bitbucket Pipelines CLI
• Validate YAML syntax before pushing
• Add debug steps to pipelines for troubleshooting

Challenge: Large Files Rejected

Solution:

• Use Git LFS (Large File Storage)

# Install Git LFS
git lfs install

# Track large file types
git lfs track "*.psd"
git lfs track "*.zip"

# Make sure .gitattributes is tracked
git add .gitattributes

# Add and commit as normal
git add file.psd
git commit -m "Add design file"
git push origin branch-name

Best Practices

Repository Organization

• Use meaningful repository names
• Organize repositories into projects
• Maintain clear README.md files
• Include license and contribution guidelines

Branching Strategy

• Gitflow:
  • master/main: Production-ready code
  • develop: Integration branch
  • feature/*: New features
  • release/*: Release preparation
  • hotfix/*: Production fixes
• GitHub Flow:
  • main: Always deployable
  • Feature branches: All development

Commit Messages

• Use present tense (“Add feature” not “Added feature”)
• Begin with issue key for Jira integration
• Keep first line under 50 characters
• Add detailed explanation after first line if needed

Security Best Practices

• Enable two-factor authentication
• Use SSH keys instead of passwords
• Never commit sensitive data (API keys, credentials)
• Set up branch restrictions for protected branches
• Regularly audit user access and permissions

Resources for Further Learning

Official Resources

• Bitbucket Documentation
• Atlassian Git Tutorials
• Bitbucket Pipelines Documentation

Community Resources

• Atlassian Community
• Stack Overflow – Bitbucket
• Bitbucket Status Page

Helpful Tools

• Sourcetree: Atlassian’s free Git GUI
• Bitbucket CLI: Command-line interface for Bitbucket
• Git hooks: Automate tasks before/after Git commands
• Bitbucket for VS Code: Extension for Visual Studio Code

This cheat sheet covers the essential aspects of working with Bitbucket. For specific use cases or advanced features, refer to the official Bitbucket documentation or community resources.