Documentation

🚀 Installation

Prerequisites

• Python 3.6 or higher
• macOS, Linux, or other Unix-like system
• Bash or Zsh shell

Quick Install

# Clone the repository
git clone https://github.com/hasinhayder/bookomark.py.git
cd bookomark.py

# Run the setup script
./setup.sh

# Restart your terminal or reload shell
source ~/.zshrc  # or source ~/.bashrc

Manual Installation

If you prefer to install manually:

1. Download the bookmark.py script
2. Make it executable: chmod +x bookmark.py
3. Add the script directory to your PATH
4. Add the bookmark function to your shell configuration

⚡ Commands Reference

Basic Commands

Management Commands

Information Commands

💡 Usage Examples

# Navigate to your project
cd ~/Projects/MyAwesomeApp

# Bookmark it
bookmark
# Enter name: myapp

# Now you can jump back from anywhere
goto
# Select: myapp

# List all bookmarks with numbers
bookmark --list
# Output:
# 1. myapp
# 2. docs
# 3. downloads

# List with full paths
bookmark --listall
# Output:
# myapp: /Users/user/Projects/MyAwesomeApp
# docs: /Users/user/Documents
# downloads: /Users/user/Downloads

# Remove bookmark for current directory
cd ~/Projects/MyAwesomeApp
bookmark --remove

# Clear all bookmarks
bookmark --flush
# Confirmation required: Are you sure? (y/N)

# Open current directory in Finder
bookmark --open

# Edit bookmarks in VS Code
bookmark --edit

🔧 Advanced Usage

Shell Integration

The bookmark function integrates seamlessly with your shell. It uses the cd command to change directories, so all shell features work as expected.

Scripting with Bookmarks

# Use in scripts
bookmark_count=$(bookmark --list | wc -l)
echo "You have $bookmark_count bookmarks"

# Navigate programmatically (example)
goto <<< "1"  # Go to first bookmark

Bookmark File Location

Bookmarks are stored in ~/.bookmarks as a simple text file with the format:

bookmark_name:/path/to/directory
another_bookmark:/another/path

Duplicate Prevention

The system automatically prevents duplicate bookmarks:

• Same directory with different names: Updates the existing bookmark
• Same name with different directories: Prompts for confirmation

🐛 Troubleshooting

Command Not Found

If you get "command not found" error:

• Make sure you ran the setup script: ./setup.sh
• Restart your terminal or run: source ~/.zshrc
• Check if the bookmark function is in your shell profile

Permission Denied

If you get permission errors:

• Make the script executable: chmod +x bookmark.py
• Check file permissions for ~/.bookmarks

Bookmarks Not Persisting

If bookmarks disappear:

• Check if ~/.bookmarks file exists and is writable
• Ensure you have write permissions in your home directory

Python Issues

If Python-related errors occur:

• Ensure Python 3.6+ is installed: python3 --version
• Try using python3 instead of python

🔄 Best Practices & Workflows

Backup & Restore Workflow

Protect your bookmarks before major system changes with this recommended workflow:

# Create a timestamped backup
bookmark --backup
# Creates: ~/bookmark-backup-YYYY-MM-DD-HHMMSS.txt

# Verify backup was created
ls ~/bookmark-backup-*.txt

# View current bookmarks before changes
bookmark --listall

# Restore from backup file
bookmark --restore ~/bookmark-backup-2025-01-15-143022.txt

# Verify restoration worked
bookmark --listall

# Test navigation to ensure paths are valid
goto

# Add to your crontab (crontab -e)
0 0 * * 0 /path/to/bookmark.py --backup

Organizing Your Bookmarks

Use these naming conventions to keep your bookmarks organized:

Integration with Other Tools

Combine bookmarks with other terminal tools for maximum efficiency:

# Add to your ~/.zshrc or ~/.bashrc

# Bookmark current dir with automatic naming
function bmhere() {
    local name=${PWD##*/}  # Use current directory name
    echo "$name" | bookmark
}

# Bookmark and immediately list to verify
function bm() {
    bookmark && bookmark --listall
}

# Quick backup before risky operations
alias safe='bookmark --backup && echo "Bookmarks backed up safely!"'

Regular Maintenance

Keep your bookmarks clean and efficient:

❓ Frequently Asked Questions

Can I use this on Windows?

Currently, the tool is designed for Unix-like systems (macOS, Linux). Windows support via WSL should work but is not officially tested.

How many bookmarks can I have?

There's no hard limit, but for practical use, keeping it under 50 bookmarks is recommended for easy navigation.

Can I backup my bookmarks?

Yes! Use the built-in backup commands:

• bookmark --backup - Creates a timestamped backup file
• bookmark --restore - Restores from a backup file
• Manual method: Copy the ~/.dir-bookmarks.txt file

See the Best Practices & Workflows section for detailed backup workflows.

Does this work with symbolic links?

Yes, the tool resolves symbolic links to their actual paths when creating bookmarks.

Can I use spaces in bookmark names?

Yes, bookmark names can contain spaces. Just enter the name normally when prompted.

What happens if a bookmarked directory is deleted?

The bookmark will remain in the list, but attempting to navigate to it will show an error. You can remove invalid bookmarks manually.