How can I prevent composer from leaving a module's git status as a "detached head" when updating

Whenever I use composer to install or update one of my modules or themes, it downloads and overwrites the module's files into the expected directory but leaves the git status in a 'detached head' state and so subsequent development work is not staged to the expected commit until I reset the head ... which only takes a moment but ... I would prefer not to have to remember to do this each time.

Could it be the way I tag the commit of latest dev work? I git push the commit; git tag it; and git push --tags in the belief that git will not push tags and the commit simultaneously.

As an example:

A theme's complete composer.json on GitHub.

  "name": "iainhouston/pellucid_monoset",
  "description": "Drupal 8 Theme for pellucid_build",
  "type": "drupal-theme",
  "license": "GPL-2.0+",
  "keywords": ["pellucid", "php"],
  "homepage": "https://iainhouston.com",
  "minimum-stability": "dev",
  "authors": [
      "name": "Iain Houston",
      "email": "[email protected]"
  "require": { }

The theme's entries extracted from the project's composer.json

"repositories": [{
    "type": "composer",
    "url": "https://packages.drupal.org/8"
    "type": "git",
    "url": "https://github.com/iainhouston/pellucid_monoset.git"
  • Probably off-topic for Drupal Answers. But do you ensure to check out some stable version or a dev branch? Do you --prefer-dist?
    – leymannx
    Commented Mar 12, 2020 at 9:10
  • The correct / latest stable version is correctly downloaded to the expected directory. Using composer to manage Drupal modules is integral and very much on-topic for every developer and many Drupal site-builders
    – iainH
    Commented Mar 12, 2020 at 9:14
  • 1
    Absolutely, but do I understand this right, that you download a Git repo and not a project hosted on drupal.org? Then this question is more about Composer handling Git repos than specifically about Drupal, isn't it? Since the same would be true for any Git repo and that this is a Drupal module/theme is just a coincidence, I'd say.
    – leymannx
    Commented Mar 12, 2020 at 9:37
  • 2
    composer checks out the git commit hash rather than a branch if I recall correctly.
    – mradcliffe
    Commented Mar 12, 2020 at 11:36
  • 2
    I experience the same thing, despite prefer-dist on our private repo. Composer does not grab the release zip/gz from GitHub like it does for Drupal packages.
    – Kevin
    Commented Mar 12, 2020 at 18:11

1 Answer 1


mradcliffe is correct:

composer checks out the git commit hash rather than a branch if I recall correctly.

This is fairly easy to deal with though. For example, if your main branch is 8.x-1.x, then you do some work on detached head, you can commit the work on the detached head, which will give you a hash. You then check out the 8.x-1.x branch, and merge the hash. Since the detached head has the 8.x-1.x branch upstream, it can be merged back into that branch after you make your changes.


$ git status
HEAD detached at aa284c1
$ git add file.php
$ git commit -m "Committed file.php"
[detached HEAD ef37212] Comitted file.php
$ git checkout 8.x-1.x
$ git merge ef37212

If you realize early enough, you can actually just run git add on all your changed filed, then check out the 8.x-1.x branch. Then you can continue to work there, or make a commit on that branch. Or you can even create a new branch from 8.x-1.x and continue your work in that branch.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.