OSMIUM-DERIVE-CHANGES(1)

📦
version 1.19.1 · 6 versions
, in fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 OSMIUM-DERIVE-CHANGES 💖

okay bestie, welcome to osmium-derive-changes — that's section 1 of the manual, we're in the big leagues now. this one's your girl for turning two OSM files into a change file. let's go 🦋

✨ NAME ✨

osmium-derive-changes — create OSM change files from two OSM data files

🌸 SYNOPSIS 🌸

osmium derive-changes [OPTIONS] OSM-FILE1 OSM-FILE2

💅 DESCRIPTION 💅

so the whole vibe here is: you hand over two OSM files and this command finds the differences between them and makes a change file out of those differences. and the change file is built in such a way that you could apply it on top of OSM-FILE1 to re-create OSM-FILE2. that's the whole point. periodt.

both input files must be sorted by type, ID, and version. and OSM-FILE1 has to be from a point in time before OSM-FILE2. no time-traveling backwards, bestie.

now, important: only object type, id, and version are compared. so this program will not detect differences in, like, the tags — unless the object has a whole new version, which is literally the normal way things work in OSM. if you actually need to compare all the data in OSM files, go look at the osmium diff program instead. different tool, different job. 🙈

for this command to create a proper change file you have to set the --output option or the --output-format option in a way that it will generate an .osc file — typically by using something like -o out.osc.gz. you can create any other OSM file format, but that is usually not what you want, and osmium derive-changes will warn you in this case. consider yourself warned. 💀

okay now the caveat section, and it matters, so read it fr fr:

for objects that are in OSM-FILE1 but not in OSM-FILE2, a "deleted" entry will be created in the output. but here's the thing — because we can not know when this deletion actually occurred, in which changeset, and by which user, it is unclear what attributes this deleted object should have. 😭 also, if you are working with extracts, the object might not actually have been deleted in the OSM database at all — it might just have been moved out of the extract you are looking at. so a real, new, "deleted" version was never created. like, it never happened, no cap.

usually the "deleted" object will get the same version number and timestamp as the object in OSM-FILE1 had, and all other information will be removed. but you can change this using the --increment-version, --keep-details, and --update-timestamp options. depending on which software you are using the change files with, different settings might be necessary. so like, check what your downstream tool wants. 💜

this command reads its input files only once and writes its output file in one go, so it can be streamed — ie. it can read from STDIN and write to STDOUT. iconic behaviour honestly. ✨

👑 OPTIONS 👑

  • --increment-version — Increment version number of deleted objects. little glow-up for the version number. ⭐
  • --keep-details — Keep details of deleted objects. Usually only id, version, and timestamp are kept. If this option is set, all attributes, all tags, and all nodes or members for ways and relations, respectively, are kept. it's giving hoarder, but respectfully. 🎀
  • --update-timestamp — Update timestamp of deleted objects to the current time. This is the same behaviour as Osmosis. 🫶

🌈 COMMON OPTIONS 🌈

  • -h, --help — Show usage help. your lil bestie when you're lost.
  • -v, --verbose — Set verbose mode. The program will output information about what it is doing to STDERR. she'll narrate her own life. 💅
  • --progress — Show progress bar. Usually a progress bar is only displayed if STDOUT and STDERR are detected to be TTY. With this option a progress bar is always shown. Note that a progress bar will never be shown when reading from STDIN or a pipe.
  • --no-progress — Do not show progress bar. Usually a progress bar is displayed if STDOUT and STDERR are detected to be a TTY. With this option the progress bar is suppressed. Note that a progress bar will never be shown when reading from STDIN or a pipe. (same pipe rule, it's the law 🚫)

🦋 INPUT OPTIONS 🦋

  • -F, --input-format=FORMAT — The format of the input file(s). Can be used to set the input format if it can't be autodetected from the file name(s). This will set the format for all input files — there is no way to set the format for some input files only. See osmium-file-formats(5) or the libosmium manual for details. one format to rule them all, sorry. 👑

🎀 OUTPUT OPTIONS 🎀

  • -f, --output-format=FORMAT — The format of the output file. Can be used to set the output file format if it can't be autodetected from the output file name. See osmium-file-formats(5) or the libosmium manual for details.
  • --fsync — Call fsync after writing the output file to force flushing buffers to disk. making sure it's really on disk, not just vibing in a buffer. 💾
  • --generator=NAME — The name and version of the program generating the output file. It will be added to the header of the output file. Default is "osmium/" and the version of osmium.
  • -o, --output=FILE — Name of the output file. Default is - (STDOUT). the classic.
  • -O, --overwrite — Allow an existing output file to be overwritten. Normally osmium will refuse to write over an existing file. she's polite like that, so you need to say please. 🙈
  • --output-header=OPTION=VALUE — Add output header option. This command line option can be used multiple times for different OPTIONs. See the osmium-output-headers(5) man page for a list of available header options. For some commands you can use the special format "OPTION!" (ie. an exclamation mark after the OPTION and no value set) to set the value to the same as in the input file. ✨

💀 DIAGNOSTICS 💀

osmium derive-changes exits with exit code

  1. 0 — if everything went alright,
  2. 1 — if there was an error processing the data, or
  3. 2 — if there was a problem with the command line arguments.

🧚 MEMORY USAGE 🧚

osmium derive-changes doesn't keep a lot of data in memory. lowkey efficient, highkey slay. 💖

🌟 EXAMPLES 🌟

Find changes in Nepal extract in January 2016:

osmium derive-changes nepal-20160101.osm.pbf nepal-20160201.osm.pbf -o nepal-jan.osc.bz2

🔥 SEE ALSO 🔥

Copyright (C) 2013-2026 Jochen Topf <jochen@topf.org>.

License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. (no warranty bestie, we said what we said 😭)

🍓 CONTACT 🍓

If you have any questions or want to report a bug, please go to https://osmcode.org/contact.html

💖 AUTHORS 💖

Jochen Topf <jochen@topf.org>.

okay that's the whole thing, go derive some changes, you absolute icon. this was osmium-derive-changes, section 1, from the 1.19.1 release of osmium — mwah, bye bestie 🫶✨💅

📦 where this page comes from