MATCH(1)

📦
version 0.24 · 5 versions
, in epel 10, epel 9, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 MATCH(1) — like, the manual page, but make it make sense 💖

okay bestie, sit down, hydrate, because this is the manual page for Match (yes, that's the MATCH(1) situation) and we're gonna get through it together. no cap.

✨ NAME ✨

Match — match catalogs by 1D or 2D positions 🦋

🌸 SYNOPSIS 🌸

astmatch [OPTION...] ASTRdata

that's it. that's the whole vibe. one program, some options, and an input catalog. 💅

🎀 DESCRIPTION 🎀

so Match is part of GNU Astronomy Utilities 0.24 ✨ and what it does is match catalogs of objects — and by default it hands you back the re-arranged matching inputs. iconic behaviour honestly.

there's also an optional log file, and if you ask for it, it gives you the low-level tea about the match — we're talking the indexs and the distances. yes, "indexs". that's what it says. we don't fix it, we respect it. 🙈

for more info, you can literally just run any of these commands. and heads up: the second one has a very comprehensive explanation of how Match gets invoked — the expected input(s), the output(s), and a full description of all the options. like, everything.

all options and their values:

$ astmatch -P

inputs/outputs and options:

$ info astmatch

full section in manual/book:

$ info Match

full Gnuastro manual/book:

$ info gnuastro

and if the manual just isn't answering your question (been there 😭), you can get direct help from experienced Gnuastro users and developers. for more info, run:

$ info help-gnuastro

Match options:

🔍 Input: 🔍

  • -h, --hdu=STR/INT — extension name or number of the first input. 🫶
  • -H, --hdu2=STR/INT — extension name or number of the second input. two inputs, two HDUs, we stay organized.
  • -I, --ignorecase — ignore case when matching/searching columns. uppercase? lowercase? she doesn't care. 💅
  • --searchin=STR — pick which column(s) to search in: 'name', 'unit', 'comment'.
  • --stdintimeout=INT — micro-seconds to wait for standard input. give stdin a little grace period. ⏳

📤 Output: 📤

  • -A, --arrange=STR — one of inner, outer, outer-within-aperture or full. this is the rearrangement personality you're choosing. ✨
  • -D, --dontdelete — don't delete the output if it already exists. it stays. it's protected. 🛡️
  • -K, --keepinputdir — keep the input directory for the automatic output.
  • -l, --logasoutput — no rearranging of inputs, the output is the log file. plot twist. 💀
  • --notmatched — output is the rows that don't match. the leftovers get their moment. 🍓
  • --outcols=STR — output columns, in CSV. 'a' means the 1st input, 'b' means the 2nd input.
  • --outfitsnocommit — no Git commit in the 0-th HDU of the output FITS.
  • --outfitsnoconfig — no metadata in the 0-th HDU of the output FITS.
  • --outfitsnodate — no 'DATE' in the 0-th HDU of the output FITS.
  • --outfitsnoversions — no versions in the 0-th HDU of the output FITS.
  • -o, --output=STR — output file name. name your baby. 👑
  • --tableformat=STR — table format: 'fits-ascii', 'fits-binary', 'txt'.
  • --wcslinearmatrix=STR — the WCS linear matrix of the output, either 'pc' or 'cd'.

💫 Catalog matching 💫

  • -a, --aperture=FLT[,...] — acceptable aperture for matching. how close counts as "close enough". 🌸
  • -c, --ccol1=STR[,STR] — column name/number of the first catalog.
  • -C, --ccol2=STR[,STR] — column name/number of the second catalog.
  • -d, --coord=FLT[,FLT] — manually input coordiantes. (spelling exactly as it ships, bestie — we don't touch it 🫶)
  • --kdtreehdu=STR — HDU of the k-d tree when --kdtree=FILE.fits.
  • -k, --kdtree=STR — build, internal, disable, or a CUSTOM-FITS-FILE.

⚙️ Operating modes: ⚙️

  • -?, --help — give this help list. 📋
  • --checkconfig — list all config files and variables that get read.
  • --cite — BibTeX citation for this program. cite your sources, queen. 📚
  • --config=STR — read configuration file STR immediately.
  • --config-prefix=STR — custom prefix of option names in config files.
  • --lastconfig — do not parse any more configuration files. that's a wrap. 🛑
  • --log — information about output(s) in a log file.
  • --minmapsize=INT — minimum bytes to avoid RAM automatically.
  • -N, --numthreads=INT — number of CPU threads to use. go fast. 🔥
  • --onlyversion=STR — only run if the program version is STR.
  • -P, --printparams — print parameter values to be used and abort.
  • --quietmmap — don't print the mmap'd file's name and size.
  • -q, --quiet — only report errors, stay quiet about the steps. no commentary, just results. 🤫
  • -S, --setdirconf — set default values for this directory and abort.
  • --usage — give a short usage message.
  • -U, --setusrconf — set default values for this user and abort.
  • -V, --version — print program version.
mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options. (say it with me: long option rules apply to the short option too. periodt. 💅)

GNU Astronomy Utilities home page: http://www.gnu.org/software/gnuastro/

🐛 REPORTING BUGS 🐛

found a bug? report it to bug-gnuastro@gnu.org. they wanna know, fr fr. 🫶

Copyright © 2015-2025 Free Software Foundation, Inc. License GPLv3+: GNU General public license version 3 or later.

this is free software: you are free to change and redistribute it. there is NO WARRANTY, to the extent permitted by law. (like, none. zero. don't come for them if it goes sideways. 😭)

written/developed by Mohammad Akhlaghi 👑

👀 SEE ALSO 👀

the full documentation for Match is maintained as a Texinfo manual. if the info and Match programs are properly installed at your site, the command

info Match

should give you access to the complete manual. go read it, bestie, it's giving comprehensive. 💖

and that's the whole page!! GNU Astronomy Utilities 0.24, dated November 2025 — mwah, slay, you're officially a Match understander now. go match some catalogs. 🦋✨🎀

📦 where this page comes from