What Is flag_order.txt and How Does It Sort Country Flags in Free-TV/IPTV?

flag_order.txt is the authoritative sorting guide that defines the display order of country flags on the main page of the Free-TV/IPTV repository by providing an ordered list of country identifiers processed by make_flags.sh.

The Free-TV/IPTV project organizes television channel lists by country, displaying a horizontal flag bar in the README.md for quick navigation. The flag_order.txt file acts as the single source of truth for the visual sequence of these flags, allowing maintainers to customize the geographic layout without manually editing the final documentation.

How flag_order.txt Controls Flag Display Order

The flag_order.txt file in the repository root serves as a declarative configuration that groups countries into logical sections such as Anglosphere, Asia, Europe, Middle East, Americas, and Africa.

Each line in the file contains a country identifier (e.g., usa, uk, japan) that corresponds to a specific markdown list file in the lists/ directory. The script make_flags.sh processes these identifiers sequentially, meaning the visual order of flags in the README directly mirrors the line order in flag_order.txt.

The file supports organizational formatting:

• Blank lines are ignored during processing
• Comment lines starting with # are filtered out
• Underscores in identifiers represent spaces (e.g., czech_republic)

The make_flags.sh Processing Pipeline

According to the Free-TV/IPTV source code, the shell script make_flags.sh implements the logic that transforms the raw text file into clickable flag icons.

Reading and Filtering the List

The script iterates over flag_order.txt using a loop that explicitly removes blank lines and comments:

for country in `cat ./flag_order.txt | grep -v "^$" | grep -v "#"`; do
    # Processing logic here

done

This ensures that only valid country identifiers enter the processing pipeline.

Transforming Identifiers to Country Codes

For each identifier, the script performs several normalizations:

• Converts underscores to spaces using sed -e "s/_/ /g"
• Handles special cases for korea (mapped to "south korea") and uk (mapped to "united kingdom")
• Looks up the two-letter ISO code from countries.list

The script then generates Markdown image links pointing to the Circle Flags CDN:

echo "[<img src=\"https://hatscripts.github.io/circle-flags/flags/$country_code.svg\" width=\"24\">](lists/$country.md)"

For example, the identifier usa produces:

[<img src="https://hatscripts.github.io/circle-flags/flags/us.svg" width="24">](lists/usa.md)

Customizing Country Display Order

To rearrange, add, or remove countries from the flag bar, edit flag_order.txt directly. After modifying the file, run make_flags.sh to regenerate the flag bar section of the README.

The script validates every entry against countries.list and exits with an error if an identifier lacks a corresponding ISO code:

if [[ -z "$country_code_line" ]]; then
    echo "MISSING COUNTRY CODE FOR: $country"
    exit 1
fi

This validation ensures that the generated README only contains valid, resolvable country links.

Summary

• flag_order.txt defines the authoritative display order for country flags in the Free-TV/IPTV repository.
• The file uses simple line-based ordering where each line represents a country identifier, with blank lines and # comments ignored.
• make_flags.sh reads this file sequentially, looks up ISO codes in countries.list, and generates Markdown flag links.
• Editing flag_order.txt and re-running the script automatically updates the visual flag bar in README.md without manual HTML manipulation.

Frequently Asked Questions

What format does flag_order.txt use?

The file uses plain text with one country identifier per line. Identifiers use underscores instead of spaces (e.g., united_kingdom), and lines beginning with # are treated as comments. The order of lines determines the final left-to-right display of flags in the README.

How does make_flags.sh handle comments and blank lines?

The script filters out both empty lines and comments using chained grep commands: grep -v "^$" removes blank lines, and grep -v "#" removes comment lines. This ensures the loop only processes valid country identifiers.

Can I add new countries to the flag bar?

Yes. Add the country identifier to flag_order.txt in your desired position, ensure the corresponding countries.list entry exists with the proper ISO code, and run make_flags.sh. The script validates the entry and generates the appropriate flag link if the country code is found.

Where does the flag imagery come from?

The script generates URLs pointing to the Circle Flags CDN (https://hatscripts.github.io/circle-flags/flags/), appending the lowercase two-letter ISO country code and .svg extension. The width is fixed at 24 pixels to maintain consistent alignment in the flag bar.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}