Add READMEs to hooks and mapmerge2 directories (#34511)

tools/hooks/README.md

@@ -0,0 +1,36 @@
+# Git Integration Hooks
+
+This folder contains installable scripts for [Git hooks] and [merge drivers].
+Use of these hooks and drivers is optional and they must be installed
+explicitly before they take effect.
+
+To install the current set of hooks, or update if new hooks are added, run
+`install.bat` (Windows) or `install.sh` (Unix-like) as appropriate.
+
+Hooks expect a Unix-like environment on the backend. Usually this is handled
+automatically by GUI tools like TortoiseGit and GitHub for Windows, but
+[Git for Windows] is an option if you prefer to use a CLI even on Windows.
+
+## Current Hooks
+
+* **Pre-commit**: Runs [mapmerge2] on changed maps, if any.
+
+## Adding New Hooks
+
+New [Git hooks] may be added by creating a file named `<hook-name>.hook` in
+this directory. Git determines what hooks are available and what their names
+are. The install script copies the `.hook` file into `.git/hooks`, so editing
+the `.hook` file will require a reinstall.
+
+New [merge drivers] may be added by adding a shell script named `<ext>.merge`
+and updating `.gitattributes` in the root of the repository to include the line
+`*.<ext> merge=<ext>`. The install script will set up the merge driver to point
+to the `.merge` file directly, and editing it will not require a reinstall.
+
+`tools/hooks/python.sh` may be used as a trampoline to ensure that the correct
+version of Python is found.
+
+[Git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks
+[merge drivers]: https://git-scm.com/docs/gitattributes#_performing_a_three_way_merge
+[Git for Windows]: https://gitforwindows.org/
+[mapmerge2]: ../mapmerge2/README.md

tools/mapmerge2/README.md

@@ -0,0 +1,52 @@
+# Map Merge 2
+
+**Map Merge 2** is an improvement over previous map merging scripts, with
+better merge-conflict prevention, multi-Z support, and automatic handling of
+key overflow. For up-to-date tips and tricks, also visit the [Map Merger] wiki article.
+
+## What Map Merging Is
+
+The "map merge" operation describes the process of rewriting a map file written
+by the DreamMaker map editor to A) use a format more amenable to Git's conflict
+resolution and B) differ in the least amount textually from the previous
+version of the map while maintaining all the actual changes. It requires an old
+version of the map to use as a reference and a new version of the map which
+contains the desired changes.
+
+## Installation
+
+To install Python dependencies, run `requirements-install.bat`, or run
+`python -m pip install -r requirements.txt` directly. See the [Git hooks]
+documentation to install the Git pre-commit hook which runs the map merger
+automatically, or use `tools/mapmerge/Prepare Maps.bat` to save backups before
+running `mapmerge.bat`.
+
+For up-to-date installation and detailed troubleshooting instructions, visit
+the [Map Merger] wiki article.
+
+## Code Structure
+
+Frontend scripts are meant to be run directly. They obey the environment
+variables `TGM` to set whether files are saved in TGM (1) or DMM (0) format,
+and `MAPROOT` to determine where maps are kept. By default, TGM is used and
+the map root is autodetected. Each script may either prompt for the desired map
+or be run with command-line parameters indicating which maps to act on. The
+scripts include:
+
+* `convert.py` for converting maps to and from the TGM format. Used by
+  `tgm2dmm.bat` and `dmm2tgm.bat`.
+* `mapmerge.py` for running the map merge on map backups saved by
+  `Prepare Maps.bat`. Used by `mapmerge.bat`
+
+Implementation modules:
+
+* `dmm.py` includes the map reader and writer.
+* `mapmerge.py` includes the implementation of the map merge operation.
+* `frontend.py` includes the common code for the frontend scripts.
+
+`precommit.py` is run by the [Git hooks] if installed, and merges the new
+version of any map saved in the index (`git add`ed) with the old version stored
+in Git when run.
+
+[Map Merger]: https://tgstation13.org/wiki/Map_Merger
+[Git hooks]: ../hooks/README.md