Merge pull request OSGeo#11723 from rouault/fix_11709

Doc: add a Migration guide to "gdal" command line interface, and show examples of bash completion

doc/source/programs/gdal.rst

@@ -65,3 +65,113 @@ Examples
    .. code-block:: console
 
        $ gdal --formats --json
+
+
+Bash completion
+---------------
+
+If Bash is used as an interactive shell, users can benefit from completion,
+using the <TAB> key. Bash completion is enabled by first sourcing the
+:file:`${install_prefix}/share/bash-completion/completions/gdal` file, which
+should be automatically done on a number of binary distributions of GDAL.
+
+Examples of completion
+++++++++++++++++++++++
+
+.. example::
+   :title: Listing sub-commands of "gdal":
+
+   .. code-block:: console
+
+        $ gdal <TAB><TAB>
+        ==>
+        convert   info      pipeline  raster    vector
+
+
+.. example::
+   :title: Completion of a sub-command from its initial letters:
+
+   .. code-block:: console
+
+        $ gdal r<TAB>
+        ==>
+        $ gdal raster
+
+
+.. example::
+   :title: Listing sub-commands of "gdal raster":
+
+   .. code-block:: console
+
+        $ gdal raster<TAB><TAB>
+        ==>
+        convert    edit       info       pipeline   reproject
+
+
+.. example::
+   :title: Listing switches of "gdal raster"
+
+   .. code-block:: console
+
+        $ gdal raster -<TAB><TAB>
+        ==>
+        --approx-stats   -f               --help           --if             --json-usage     --min-max        --no-fl          --no-md          --oo             --stats
+        --checksum       --format         --hist           --input          --list-mdd       --mm             --no-gcp         --no-nodata      --open-option    --subdataset
+        --drivers        -h               -i               --input-format   --mdd            --no-ct          --no-mask        --of             --output-format  --version
+
+.. example::
+   :title: Listing allowed values for a switch
+
+   .. code-block:: console
+
+        $ gdal raster info --of=<TAB><TAB>
+        ==>
+        json  text
+
+.. example::
+   :title: Listing allowed creation options, restricted to those valid for the output format, once the output filename has been specified
+
+   .. code-block:: console
+
+        $ gdal raster convert in.tif out.tif --co <TAB><TAB>
+        ==>
+        ALPHA=                           ENDIANNESS=                      JXL_EFFORT=                      PIXELTYPE=                       SOURCE_PRIMARIES_RED=            TIFFTAG_TRANSFERRANGE_BLACK=
+        BIGTIFF=                         GEOTIFF_KEYS_FLAVOR=             JXL_LOSSLESS=                    PREDICTOR=                       SOURCE_WHITEPOINT=               TIFFTAG_TRANSFERRANGE_WHITE=
+        BLOCKXSIZE=                      GEOTIFF_VERSION=                 LZMA_PRESET=                     PROFILE=                         SPARSE_OK=                       TILED=
+        [ ... snip ... ]
+
+
+.. example::
+   :title: Listing known configuration options starting with AWS
+
+   .. code-block:: console
+
+        $ gdal --config AWS_<TAB><TAB>
+        ==>
+        AWS_ACCESS_KEY_ID=                       AWS_DEFAULT_REGION=                      AWS_REQUEST_PAYER=                       AWS_STS_ENDPOINT=
+        AWS_CONFIG_FILE=                         AWS_HTTPS=                               AWS_ROLE_ARN=                            AWS_STS_REGION=
+        AWS_CONTAINER_AUTHORIZATION_TOKEN=       AWS_MAX_KEYS=                            AWS_ROLE_SESSION_NAME=                   AWS_STS_REGIONAL_ENDPOINTS=
+        AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE=  AWS_NO_SIGN_REQUEST=                     AWS_S3_ENDPOINT=                         AWS_TIMESTAMP=
+        AWS_CONTAINER_CREDENTIALS_FULL_URI=      AWS_PROFILE=                             AWS_SECRET_ACCESS_KEY=                   AWS_VIRTUAL_HOSTING=
+        AWS_DEFAULT_PROFILE=                     AWS_REGION=                              AWS_SESSION_TOKEN=                       AWS_WEB_IDENTITY_TOKEN_FILE=
+
+
+.. example::
+   :title: Auto-completion of EPSG CRS codes
+
+   .. code-block:: console
+
+        $ gdal raster reproject --dst-crs EPSG:432<TAB>
+        ==>
+        4322 -- WGS 72                  4324 -- WGS 72BE                4326 -- WGS 84                  4327 -- WGS 84 (geographic 3D)  4328 -- WGS 84 (geocentric)     4329 -- WGS 84 (3D)
+
+.. example::
+   :title: Auto-completion of filenames in a cloud storage (assuming credentials are properly set up)
+
+   .. code-block:: console
+
+        $ gdal raster info /vsis3/my_bucket/b<TAB><TAB>
+        ==>
+        /vsis3/my_bucket/byte.tif      /vsis3/my_bucket/byte2.tif
+
+

doc/source/programs/index.rst

@@ -25,6 +25,7 @@ single :program:`gdal` program that accepts commands and subcommands.
    :maxdepth: 1
    :hidden:
 
+   migration_guide_to_gdal_cli
    gdal
    gdal_info
    gdal_convert
@@ -48,6 +49,7 @@ single :program:`gdal` program that accepts commands and subcommands.
 
 .. only:: html
 
+    - :ref:`migration_guide_to_gdal_cli`: Migration guide to "gdal" command line interface
     - :ref:`gdal_program`: Main "gdal" entry point
     - :ref:`gdal_info_command`: Get information on a dataset
     - :ref:`gdal_convert_command`: Convert a dataset

doc/source/programs/migration_guide_to_gdal_cli.rst

@@ -0,0 +1,184 @@
+.. _migration_guide_to_gdal_cli:
+
+================================================================================
+Migration guide to "gdal" command line interface
+================================================================================
+
+This page documents through examples how to migrate from the traditional GDAL
+command line utilities to the unified "gdal" command line interface added in
+GDAL 3.11.
+
+Raster commands
+---------------
+
+* Getting information on a raster dataset in human-readable format
+
+.. code-block::
+
+    gdalinfo my.tif
+
+    ==>
+
+    gdal raster info --format=text my.tif
+
+
+* Converting a georeferenced netCDF file to cloud-optimized GeoTIFF
+
+.. code-block::
+
+    gdal_translate -of COG in.nc out.tif
+
+    ==>
+
+    gdal raster convert --of=COG in.nc out.tif
+
+
+* Reprojecting a GeoTIFF file to a Deflate compressed tiled GeoTIFF file
+
+.. code-block::
+
+    gdalwarp -t_srs EPSG:4326 -co TILED=YES -co COMPRESS=DEFLATE -overwrite in.tif out.tif
+
+    ==>
+
+    gdal raster reproject --dst-crs=EPSG:4326 --co=TILED=YES,COMPRESS=DEFLATE --overwrite in.tif out.tif
+
+
+* Converting a PNG file to a tiled GeoTIFF file, adding georeferencing for world coverage in WGS 84 and metadata
+
+.. code-block::
+
+    gdal_translate -a_ullr -180 90 180 -90 -a_srs EPSG:4326 -co TILED=YES -mo DESCRIPTION=Mean_day_temperature in.png out.tif
+
+    ==>
+
+    gdal raster pipeline read in.png ! edit --crs=EPSG:4326 --bbox=-180,-90,180,90 --metadata=DESCRIPTION=Mean_day_temperature ! write --co=TILED=YES out.tif
+
+Note that the order of elements differ: "upper-left-x upper-left-y lower-right-x lower-right-y" for gdal_translate,
+compared to "minimum-x,minimum-y,maximum-x,maximum-y" for the ``--bbox`` option of "gdal raster pipeline ... edit".
+
+
+* Clipping a raster with a bounding box
+
+.. code-block::
+
+    gdal_translate -projwin 2 50 3 49 in.tif out.tif
+
+    ==>
+
+    gdal raster clip --bbox=2,49,3,50 in.tif out.tif
+
+
+* Creating a virtual mosaic (.vrt) from all GeoTIFF files in a directory
+
+.. code-block::
+
+    gdalbuildvrt out.vrt src/*.tif
+
+    ==>
+
+    gdal raster mosaic src/*.tif out.vrt
+
+
+* Creating a mosaic in COG format from all GeoTIFF files in a directory
+
+.. code-block::
+
+    gdalbuildvrt tmp.vrt src/*.tif
+    gdal_translate -of COG tmp.vrt out.tif
+
+    ==>
+
+    gdal raster mosaic --of=COG src/*.tif out.tif
+
+
+* Adding internal overviews for reduction factors 2, 4, 8 and 16 to a GeoTIFF file
+
+.. code-block::
+
+    gdaladdo -r average my.tif 2 4 8 16
+
+    ==>
+
+    gdal raster overview add -r average --levels=2,4,8,16 my.tif
+
+
+* Combining single-band rasters into a multi-band raster
+
+.. code-block::
+
+    gdalbuildvrt tmp.vrt red.tif green.tif blue.tif
+    gdal_translate tmp.vrt out.tif
+
+    ==>
+
+    gdal raster stack red.tif green.tif blue.tif out.tif
+
+
+Vector commands
+---------------
+
+* Getting information on a vector dataset in human-readable format
+
+.. code-block::
+
+    ogrinfo -al -so my.gpkg
+
+    ==>
+
+    gdal vector info --format=text my.gpkg
+
+
+* Converting a shapefile to a GeoPackage
+
+.. code-block::
+
+    ogr2ogr out.gpkg in.shp
+
+    ==>
+
+    gdal vector convert in.shp out.gpkg
+
+
+* Reprojecting a shapefile to a GeoPackage
+
+.. code-block::
+
+    ogr2ogr -t_srs EPSG:4326 out.gpkg in.shp
+
+    ==>
+
+    gdal vector reproject --dst-crs=EPSG:4326 in.shp out.gpkg
+
+
+* Clipping a GeoPackage file
+
+.. code-block::
+
+    ogr2ogr -clipsrc 2 49 3 50 out.gpkg in.shp
+
+    ==>
+
+    gdal vector clip --bbox=2,49,3,50 in.gpkg out.gpkg
+
+
+* Selecting features from a GeoPackage file intersecting a bounding box, but not clipping them to it
+
+.. code-block::
+
+    ogr2ogr -spat 2 49 3 50 out.gpkg in.shp
+
+    ==>
+
+    gdal vector filter --bbox=2,49,3,50 in.gpkg out.gpkg
+
+
+*  Selecting features from a GeoPackage file intersecting a bounding box, but not clipping them to it and reprojecting
+
+.. code-block::
+
+    ogr2ogr -t_srs EPSG:32631 -spat 2 49 3 50 out.gpkg in.shp
+
+    ==>
+
+    gdal vector pipeline read in.gpkg ! filter --bbox=2,49,3,50 ! reproject --dst-crs=EPSG:32631 ! write out.gpkg