borg list. how to format with newlines

When working with BorgBackup, formatting the output of the borg list command is essential for readability, especially if you're looking to separate items with newlines. Below is a thorough guide on how to achieve this, along with key insights into the borg list command's functionality.

Understanding the borg list Command

The borg list command is utilized for listing the contents of a repository or an archive in BorgBackup. It provides a structured way to visualize files, directories, and archives you've backed up. To enhance the output's clarity, especially when dealing with large repositories, formatting can be adjusted using several command-line options.

Formatting Output with Newlines

To format the output of borg list with newlines specifically, you will leverage the --format option, which defines how each item is displayed. Here’s how to do it:

Basic Command Structure

borg list [REPOSITORY] --format '{id} {file_name}\n'

Example Usage

1. List all items with newlines:

   If you want to list the contents of a Borg repository and ensure each item appears on a new line, you could execute:

   borg list /path/to/repo --format '{path}\n'
   

   In this command:

   • Replace /path/to/repo with your actual repository path.
   • {path} refers to the full path of each file or directory listed.
   • The \n at the end adds a newline after each listed item.

2. Custom Formats:

   You can customize the format further if you want to include other metadata—like the size or modification time—while still ensuring each piece of information appears clearly on a new line. For example:

   borg list /path/to/repo --format '{time:%y-%m-%d %H:%M:%S} {size} {path}\n'
   

   This will produce output formatted like:

   2025-10-02 14:30:12 200KB /file1.txt
   2025-10-02 14:31:23 300KB /file2.txt
   

Using JSON or JSON Lines

If you prefer machine-readable formats, BorgBackup supports outputting in JSON format. While the --json-lines option doesn't allow for direct newline formatting in the same way, it still provides clear formatting for processing in scripts.

borg list /path/to/repo --json-lines

This command outputs each item as a JSON object on a separate line, suitable for parsing by other tools, albeit without the customizable formatting options of the --format flag.

Additional Tips

• For extended help on borg list and its formatting options, you can refer to the Borg Backup documentation here.
• Experiment with different placeholders in the --format option to cater to your specific output requirements. The available placeholders include {path}, {size}, {mtime}, and others.

Conclusion

Formatting the output of the borg list command with newlines is a straightforward process using the --format option. This allows you to tailor the information for better readability, making it easier to analyze or share with others. For complex needs or automation, consider leveraging JSON formats. BorgBackup’s flexibility makes it a robust tool for backup management, accommodating various styles of output suited to your workflow.