From 2d01a3d68fe8a9e122d0c3ab80b4a4be8746c625 Mon Sep 17 00:00:00 2001 From: velle Date: Thu, 30 Jan 2025 19:37:56 +0100 Subject: [PATCH 1/7] Update qgis_file_formats.rst Article had no information about XXXXXX_styles.db, so I added this. Rewrote everything related to the qgz, qgs, qgd and XXXXXX_styles.db: Added more helpful and complete explanations and examples. --- .../appendices/qgis_file_formats.rst | 98 +++++++++++-------- 1 file changed, 56 insertions(+), 42 deletions(-) diff --git a/docs/user_manual/appendices/qgis_file_formats.rst b/docs/user_manual/appendices/qgis_file_formats.rst index 4ff5945bd88..e14f5acbe98 100644 --- a/docs/user_manual/appendices/qgis_file_formats.rst +++ b/docs/user_manual/appendices/qgis_file_formats.rst @@ -10,54 +10,68 @@ Appendix C: QGIS File Formats .. index:: QGD .. _qgisprojectfile: -QGS/QGZ - The QGIS Project File Format -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The **QGS** format is an XML format for storing QGIS projects. -The **QGZ** format is a compressed (zip) archive containing a -QGS file and a QGD file. -The **QGD** file is the associated sqlite database of the qgis -project that contain auxiliary data for the project. -If there are no auxiliary data, the QGD file will be empty. - -A QGIS file contains everything that is needed for storing a QGIS -project, including: - -* project title -* project CRS -* the layer tree -* snapping settings -* relations -* the map canvas extent -* project models -* legend -* mapview docks (2D and 3D) -* the layers with links to the underlying datasets (data sources) and - other layer properties including extent, SRS, joins, styles, renderer, - blend mode, opacity and more. -* project properties - -The figures below show the top level tags in a QGS file and the expanded -``ProjectLayers`` tag. - -.. _figure_qgs_toplevel: - -.. figure:: img/qgstoplevel.png - :align: center +.qgz or .qgs- The QGIS Project File Format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The top level tags in a QGS file +When you see a file with either .qgz or .qgs extension, those are QGIS project files. -.. _figure_qgs_projectlayers: +This file format does not itself contain any geodata, ie it does not contain aerial photos and it does not contain polygon or point features representing features on a map. It only contains data _about_ which layers to show and how to show them. -.. figure:: img/qgsprojectlayers.png - :align: center - The expanded top level ProjectLayers tag of a QGS file +When you edit the name of a mountain in the layer called mountains and click `Save Layers Edit`, then that change is saved to the layer source, which might be a local GeoJson file or a remote database. But nothing is changed to the qgis project file. + +When you change QGIS to show labels with those mountain names in blue and with Comic Sans, and you click "Save Project", this data about presentation is saved to the project file. + +Evolution from qgs to qgz +^^^^^^^^^^^^^^^^^^^^^^^^^ + +QGIS version 2 only knew of one project file format, which was XML with a .qgs extension. + +But XML has its limitations and eventually it was necessary to also store project data in other ways than plain XML. + +With the introduction of QGIS 3 the default fileformat was .qgz, which is a zip archive containing the .qgs file. But because it's a zip file, it can also contain other files, so called *sidecar files*. Currently there are two official types of sidecar files: + +- .qgd (see section below) +- XXXXXX_styles.db, (see section below) + +Alternative: myproject.qgs with myproject_attachments.zip +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is however also possible to not use .qgz, and instead save a project to .qgs. If choosing so, any sidecar files will be saved to a separate zip file. E.g. when saving to myproject.qgs, the sidecar files will be written to the archive myproject_attachments.zip, placed in the same folder. + +One reason for choosing to use .qgs instead of .qgz is +that its more suited for running diff tools, e.g. if one wants to run version control on qgis project files. + +.qgs - The QGIS Project XML Format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The .qgs is an XML format, which contains the most fundamental parts of the project. This includes: + +- project title +- project CRS +- the layer tree +- snapping settings +- relations +- the map canvas extent +- project models +- legend +- mapview docks (2D and 3D) +- the layers with links to the underlying datasets (data sources) and other layer properties including extent, SRS, joins, styles, renderer, blend mode, opacity and more. +- project properties + +.qgd - Sidecar for storing auxiliary data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +One example of auxiliary data is when the project file contains data about individual features from a layer, ie data that is associated with a feature, and thus not simply associated with a layer. One example is if the user specifies label placement for individual features. + +If saving a project to foo.qgz, and the project contains any auxiliary data, then that aux data will be saved to foo.qgd which is added to the archive. If no auxiliary data is present, then this sidecar file won't be created. The d is short for databse, and the file is an sqlite3 database. + +XXXXXX_styles.db - Sidecar file for storing style information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +XXXXXX is a six character randomly generated string, so it could look like XiIaRN_styles.db or clnCHe_styles.db. -.. index:: QGIS Layer Definition File -.. index:: QLR -.. _qgislayerdefinitionfile: +Typically there is just one such sidecar file, but there might be more. They are sqlite3 databases and contain information relevant to layer styling. QLR - The QGIS Layer Definition file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 5fa6c9647d0f3860f39688c22ce0a4f0f8c9d865 Mon Sep 17 00:00:00 2001 From: velle Date: Fri, 31 Jan 2025 20:11:59 +0100 Subject: [PATCH 2/7] Update docs/user_manual/appendices/qgis_file_formats.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Serge Croisé --- docs/user_manual/appendices/qgis_file_formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/appendices/qgis_file_formats.rst b/docs/user_manual/appendices/qgis_file_formats.rst index e14f5acbe98..34b8332f855 100644 --- a/docs/user_manual/appendices/qgis_file_formats.rst +++ b/docs/user_manual/appendices/qgis_file_formats.rst @@ -64,7 +64,7 @@ The .qgs is an XML format, which contains the most fundamental parts of the proj One example of auxiliary data is when the project file contains data about individual features from a layer, ie data that is associated with a feature, and thus not simply associated with a layer. One example is if the user specifies label placement for individual features. -If saving a project to foo.qgz, and the project contains any auxiliary data, then that aux data will be saved to foo.qgd which is added to the archive. If no auxiliary data is present, then this sidecar file won't be created. The d is short for databse, and the file is an sqlite3 database. +If saving a project to foo.qgz, and the project contains any auxiliary data, then that aux data will be saved to foo.qgd which is added to the archive. If no auxiliary data is present, then this sidecar file won't be created. The d is short for database, and the file is an sqlite3 database. XXXXXX_styles.db - Sidecar file for storing style information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 80cacf014677f4ed0de25300d5021e3aea070302 Mon Sep 17 00:00:00 2001 From: velle Date: Fri, 31 Jan 2025 20:12:12 +0100 Subject: [PATCH 3/7] Update docs/user_manual/appendices/qgis_file_formats.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Serge Croisé --- docs/user_manual/appendices/qgis_file_formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/appendices/qgis_file_formats.rst b/docs/user_manual/appendices/qgis_file_formats.rst index 34b8332f855..e5e31c747f3 100644 --- a/docs/user_manual/appendices/qgis_file_formats.rst +++ b/docs/user_manual/appendices/qgis_file_formats.rst @@ -15,7 +15,7 @@ Appendix C: QGIS File Formats When you see a file with either .qgz or .qgs extension, those are QGIS project files. -This file format does not itself contain any geodata, ie it does not contain aerial photos and it does not contain polygon or point features representing features on a map. It only contains data _about_ which layers to show and how to show them. +This file format does not itself contain any geodata, i.e., it does not contain aerial photos and it does not contain polygon or point features representing features on a map. It only contains data _about_ which layers to show and how to show them. When you edit the name of a mountain in the layer called mountains and click `Save Layers Edit`, then that change is saved to the layer source, which might be a local GeoJson file or a remote database. But nothing is changed to the qgis project file. From 83d4278731ef73e917dd5ceee25525eb1ddaaa67 Mon Sep 17 00:00:00 2001 From: velle Date: Fri, 31 Jan 2025 20:12:22 +0100 Subject: [PATCH 4/7] Update docs/user_manual/appendices/qgis_file_formats.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Serge Croisé --- docs/user_manual/appendices/qgis_file_formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/appendices/qgis_file_formats.rst b/docs/user_manual/appendices/qgis_file_formats.rst index e5e31c747f3..3640d03ab18 100644 --- a/docs/user_manual/appendices/qgis_file_formats.rst +++ b/docs/user_manual/appendices/qgis_file_formats.rst @@ -29,7 +29,7 @@ QGIS version 2 only knew of one project file format, which was XML with a .qgs e But XML has its limitations and eventually it was necessary to also store project data in other ways than plain XML. -With the introduction of QGIS 3 the default fileformat was .qgz, which is a zip archive containing the .qgs file. But because it's a zip file, it can also contain other files, so called *sidecar files*. Currently there are two official types of sidecar files: +With the introduction of QGIS 3 the default file format was .qgz, which is a zip archive containing the .qgs file. But because it's a zip file, it can also contain other files, so called *sidecar files*. Currently there are two official types of sidecar files: - .qgd (see section below) - XXXXXX_styles.db, (see section below) From 7759fb1e00dbf92563e181f32d53bdd939296d2d Mon Sep 17 00:00:00 2001 From: velle Date: Fri, 31 Jan 2025 20:12:33 +0100 Subject: [PATCH 5/7] Update docs/user_manual/appendices/qgis_file_formats.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Serge Croisé --- docs/user_manual/appendices/qgis_file_formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/appendices/qgis_file_formats.rst b/docs/user_manual/appendices/qgis_file_formats.rst index 3640d03ab18..c4a96a09e4a 100644 --- a/docs/user_manual/appendices/qgis_file_formats.rst +++ b/docs/user_manual/appendices/qgis_file_formats.rst @@ -40,7 +40,7 @@ Alternative: myproject.qgs with myproject_attachments.zip It is however also possible to not use .qgz, and instead save a project to .qgs. If choosing so, any sidecar files will be saved to a separate zip file. E.g. when saving to myproject.qgs, the sidecar files will be written to the archive myproject_attachments.zip, placed in the same folder. One reason for choosing to use .qgs instead of .qgz is -that its more suited for running diff tools, e.g. if one wants to run version control on qgis project files. +that it's more suited for running diff tools, e.g., if one wants to run version control on qgis project files. .qgs - The QGIS Project XML Format ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From cc5eb8c8498fac71bda66b2eabaada4170c4915f Mon Sep 17 00:00:00 2001 From: velle Date: Fri, 31 Jan 2025 20:12:41 +0100 Subject: [PATCH 6/7] Update docs/user_manual/appendices/qgis_file_formats.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Serge Croisé --- docs/user_manual/appendices/qgis_file_formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/appendices/qgis_file_formats.rst b/docs/user_manual/appendices/qgis_file_formats.rst index c4a96a09e4a..969121bd12b 100644 --- a/docs/user_manual/appendices/qgis_file_formats.rst +++ b/docs/user_manual/appendices/qgis_file_formats.rst @@ -62,7 +62,7 @@ The .qgs is an XML format, which contains the most fundamental parts of the proj .qgd - Sidecar for storing auxiliary data ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -One example of auxiliary data is when the project file contains data about individual features from a layer, ie data that is associated with a feature, and thus not simply associated with a layer. One example is if the user specifies label placement for individual features. +One example of auxiliary data is when the project file contains data about individual features from a layer, i.e., data that is associated with a feature, and thus not simply associated with a layer. One example is if the user specifies label placement for individual features. If saving a project to foo.qgz, and the project contains any auxiliary data, then that aux data will be saved to foo.qgd which is added to the archive. If no auxiliary data is present, then this sidecar file won't be created. The d is short for database, and the file is an sqlite3 database. From d82f9a3e41e72de68d6bfa0482130e792211d1b8 Mon Sep 17 00:00:00 2001 From: velle Date: Fri, 31 Jan 2025 20:28:30 +0100 Subject: [PATCH 7/7] Update qgis_file_formats.rst --- docs/user_manual/appendices/qgis_file_formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/appendices/qgis_file_formats.rst b/docs/user_manual/appendices/qgis_file_formats.rst index 969121bd12b..bdb776e661a 100644 --- a/docs/user_manual/appendices/qgis_file_formats.rst +++ b/docs/user_manual/appendices/qgis_file_formats.rst @@ -40,7 +40,7 @@ Alternative: myproject.qgs with myproject_attachments.zip It is however also possible to not use .qgz, and instead save a project to .qgs. If choosing so, any sidecar files will be saved to a separate zip file. E.g. when saving to myproject.qgs, the sidecar files will be written to the archive myproject_attachments.zip, placed in the same folder. One reason for choosing to use .qgs instead of .qgz is -that it's more suited for running diff tools, e.g., if one wants to run version control on qgis project files. +that it's better suited for running diff tools, e.g., if one wants to run version control on qgis project files. .qgs - The QGIS Project XML Format ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^