Version:

Acquia Cohesion renames to Site Studio from version 6.2. Tell me more.

    Package management via Drush

    Install Acquia Site Studio sync

    Install the Acquia Site Studio sync module; you can do this through the UI by navigating to: /admin/modules or running the following Drush command in your terminal:

    drush pm-enable cohesion_sync -y

     

    Acquia Site Studio Sync module provides the following Drush commands which are available to use within your terminal application. 

    • sitestudio:package:list - List sync packages.

    • sitestudio:package:export - Export Site studio package files to a specified or  default directory.

    • sitestudio:package:import - Import Site Studio packages from specified or default directory.

    Configure Site Studio sync module

    Configuring your sync directory

    This is the location of your site configuration files. 

    In settings.php you will need to add a setting $settings['site_studio_sync']
    For example $settings['site_studio_sync'] = '../config/sync';

    It's possible to set the site_studio_sync directory to the same sync directory as core (which is /sync by default), or you could export to the filesystem in sites/default/files for example.

    Configuring entity types to include in the export

    With "Site Studio core" and the "Site Studio sync" modules installed, navigate to: /admin/cohesion/sync/export_settings from here you can select which entity types will be scanned for the export. This configuration only affects full package exports.

    To specify what entity types are included in individual packages use "Excluded entity types" and "Package contents" options when creating or editing a package. More information is available here.

    Package list command

    This Drush command outputs list of package names and IDs:

    sitestudio:package:list

     

    Package list command has no options. Adding -h as option will output "List sync packages." message.

    Example

    Here's the example of using the command and a sample output with single package "Blog feature" (id: pack_blog_feature):

    $ drush sitestudio:package:list
    Available Site Studio packages:
    
    Blog feature - id: pack_blog_feature

    Package export command

    To export Acquia Site Studio packages and dependencies to your sync directory, use the following Drush command:

    sitestudio:package:export
    

     

    This command has the following options:

    • --package[=PACKAGE] - Site studio Package id of specific package. If this option is omitted, full package export will be executed.
    • --path[=PATH] - Target directory. If this option is omitted, command defaults to value set in $settings['site_studio_sync'].

    Adding -h as option will output "Export Site studio package files to a path." message and the list of available options.

    Running this command will create the directory specified via --path option if it doesn't exist and permissions allows the directory to be created. In this directory, Drush command will place configuration entities exported as readable .yml files, all the dependency files such as fonts and images and a site_studio_package_files.json.

    • .yml files are exported in "pretty printed" format. This makes reviewing and keeping track of changes easier, but makes such files incompatible with traditional Drupal configuration import.
    • dependency files - are exported in the relevant format to them. For example, .png images can be viewed and edited as required in the package directory.
    • site_studio_package_files.json - contains Drupal metadata about the dependency files, such as URI, filesize, file mime type, timestamps, etc. 

    If destination path already contains exported package, the command will prompt the user to confirm the deletion of files in destination directory. If this is not confirmed, the export command will abort without deleting any of the files and without exporting anything. If confirmed, the command will first delete files in destination directory and then proceed to export the Package.

    Examples

    Here's the example prompt the user would see, if the destination directory of "sites/default/files/cohesion_sync" already contains files:

    The .yml files in your export directory (sites/default/files/cohesion_sync/) will be deleted and replaced with the package config and files. (yes/no) [yes]:
    
    >

     

    To always delete files by default, the following flags can be used: --yes or -y

    To always cancel command instead of deleting files, the following flag can be used: --no

    Here's the example output of specific package export (using package id) and specific path with confirmation flag:

    $ drush sitestudio:package:export --package=pack_blog_feature --path=--path=sites/default/files/sync/pack_blog_feature/ -y                                                 
    
    Exported 64 config and 14 non-config files. 

     

    Here's the example output of full package export with default path as specified in Site Studio $settings['site_studio_sync'] with prompt that asks user to confirm deletion existing package files before export:

    $ drush sitestudio:package:export
    
    The .yml files in your export directory (sites/default/files/cohesion_sync/) will be deleted and replaced with the package config and files. (yes/no) [yes]:
    
    > yes                                             
    
     Exported 285 config and 12 non-config files. 

     

    Here's the example of site_studio_package_files.json that contains 2 files, one image in .png format and one .ttf file:

    { 
      "file:file:f912fea9-fd41-4f12-bee2-90f6a27219bf": {
        "fid": "4",
        "uuid": "f912fea9-fd41-4f12-bee2-90f6a27219bf",
        "langcode": "en",
        "filename": "image_1.png",
        "uri": "public:\/\/image_1.png",
        "filemime": "image\/png",
        "filesize": "4594",
        "status": "1",
        "created": "1634141175",
        "changed": "1634141175" 
       },
      "file:file:b9129c1a-6416-4106-bd67-c0dea5dfda9a": {
        "fid": "290",
        "uuid": "b9129c1a-6416-4106-bd67-c0dea5dfda9a",
        "langcode": "en",
        "filename": "icomoon.ttf",
        "uri": "public:\/\/cohesion\/icomoon.ttf",
        "filemime": "application\/octet-stream",
        "filesize": "184196",
        "status": "1",
        "created": "1594199557",
        "changed": "1594199557"
       }
     }

    Package import command:

    Acquia Cohesion Sync module provides import command, that allows package imports from specified or default location. Both individual and full packages are supported:

    sitestudio:package:import

     

    This command has the following options:

    • --path[=PATH] - Specify path to a directory containing package files. If this option is omitted, command defaults to value set in $settings['site_studio_sync'].
    • --diff[=DIFF] - Show preview as a diff. If this option is provided, confirmation of changes will be required in order for import to complete, unless --yes is also used, to auto-confirm the changes.
    • --extra-validation - Import all configuration and files with default Drupal validation and perform data integrity validation on Site Studio configuration. This import takes more time and resources.

    Adding -h as option will output "Import Cohesion packages from sync." message and the list of available options.

    Package import command tracks what changes are being introduced and rebuilds relevant entities during the command process.

     

    Managing images via Package files

    It is possible to edit and update or completely replace images in located in exported Site Studio package. Even if the metadata in site_studio_package_files.json has not been updated, import command will detect the change and import the updated image.

    However, while Site Studio supports editing and updating of existing images via package import, Drupal image style caching mechanisms will not automatically refresh. If image already has existing versions of it based on "image styles", Drupal image style flush will be required in order to regenerate image styles based on updated image. More information is available here.

    Depending on the users browser, old image also might be cached until such time that the browser cache expires or is cleared.

    Example

    Here's an example of Package import and partial rebuild:

    drush sitestudio:package:import' on lightning
    
        No non-config files were imported or updated during sync.
    
     [notice] Synchronized configuration: create cohesion_custom_styles.cohesion_custom_style.6d265e77.
     [notice] Synchronized configuration: create cohesion_elements.cohesion_component.cpt_aco_1020.
     [notice] Synchronized configuration: create cohesion_elements.cohesion_component.coh_component_hero_shallow.
     [notice] Finalizing configuration synchronization.
     [success] The configuration was imported successfully.
    
                 Doing partial rebuild.
    
    >  [notice] Building cohesion_custom_style - Heading 1 size - 6d265e77
    >  [notice] Building cohesion_component - Hero - shallow - coh_component_hero_shallow
    >  [notice] Building cohesion_component - ACO-1020 - cpt_aco_1020
    >  [notice] Securing twig template directory.
    >  [notice] Flushing render cache.
    >  [notice] Message: Entities in use have been rebuilt.
    >
    
                   Rebuild complete.

    Using config split

    Exporting Drupal configuration can be done using the drush command drush cex. This command exports all your website configuration into your sync directory including Acquia Site Studio configuration, although this wouldn't include any file/image assets used within Acquia Site Studio. Using Acquia Site Studio sync to export Acquia Site Studio configuration, makes sure all file/image assets are also exported. 

    You could export all configuration and then import all your website configuration and then Acquia Site Studio configuration over the top using Acquia Site Studio sync as it will bring dependencies with it. This approach works though is not ideal. 

    Using a module such as configuration split you can then split out specific configuration by Drupal module. 
    For example, you could create a 'split' which includes all configuration except Acquia Site Studio, as you would then use Acquia Site Studio sync to export Acquia Site Studio configuration including any file/image asset used.

    Find out more about configuration split module on their online documentation.

    Legacy Drush commands

     

    The legacy package management methods described below will be removed in Site Studio 7.0.0

     

    drush cohesion:import  - Runs an Acquia Site Studio asset import from the API, this is usually run when upgrading Acquia Site Studio.
    drush cohesion:rebuild - Runs an Acquia Site Studio rebuild, this will re-save Acquia Site Studio settings, styles and templates.

    If Acquia Site Studio sync is enabled, you can use the following commands.

    drush sync:export - Exports all Acquia Site Studio configuration to the sync folder as a .yml_ file.

    drush sync:export --filename-prefix=myfilenamehere - Exports all Acquia Site Studio configuration to the sync folder as a .yml_ file with a custom file name rather than using the websites name.

    drush sync:import --overwrite-all - Imports all Acquia Site Studio packages from the sync folder and overwrite existing Acquia Site Studio configuration.

    drush sync:import --keep-all - Imports all Acquia Site Studio configuration from the sync folder and keeps existing Acquia Site Studio configuration and only imports new configuration.

    DX8 knowledge base icon

    Frequently asked questions

    Get instant answers to common questions. Available online 24/7.

    Find answers

    Raise a ticket icon

    Raise a support ticket

    To raise a ticket, sign into Acquia Cloud and select Help in the top menu.

    Raise support ticket

    Acquia

    Copyright © 2020 Acquia, Inc. All Rights Reserved. Drupal is a registered trademark of Dries Buytaert.