Netlify-cms: Editorial workflow breaks if a branch named "cms" exists

[jschill]

Describe the bug

When enabling the editorial workflow and clicking "Workflow" I get "TypeError: e.filter is not a function" pointing to this line: https://github.com/netlify/netlify-cms/blob/8e1556f9083d8d673f5f1f7de4bf68fbe0eb003a/packages/netlify-cms-core/src/backend.js#L508

To Reproduce

Expected behavior
I have never got this working so I don't know.

Screenshots

Applicable Versions:

• Netlify CMS version: 2.9.1
• Git provider: Github
• OS: macOS 10.14.4
• Browser version: chrome 74
  
• Node.JS version: n/a

CMS configuration

Repo removed

backend:
  name: github
  repo: my/repo
  branch: cms # Branch to update (optional; defaults to master)
publish_mode: editorial_workflow
media_folder: "static/assets/img/blog/uploads"
public_folder: "/assets/img/blog/uploads"
collections:
  - name: "blog" # Used in routes, e.g., /admin/collections/blog
    label: "Blog" # Used in the UI
    folder: "content/blog" # The path to the folder where the documents are stored
    create: true # Allow users to create new documents in this collection
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}" # Filename template, e.g., YYYY-MM-DD-title.md
    fields: # The fields for each document, usually in front matter
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Author", name: "author", widget: "string"} # Fix widget
      - {label: "Publish Date", name: "date", widget: "date", format: "MMM Do YY"}
      - {label: "Categories", name: "categories", widget: "list"}
      - {label: "Keywords", name: "keywords", widget: "list"}
      - {label: "Cover image", name: "cover_image", widget: "image"}
      - {label: "Cover opacity", name: "cover_opacity", widget: "number", default: 0.4, valueType: "float", min: 0.1, max: 1.0, step: 0.1}
      - {label: "Cover blur", name: "cover_blur", widget: "string", default: "1px"}
      - {label: "Description", name: "description", widget: "string"}
      - {label: "Excerpt", name: "excerpt", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}

Additional context

Seems like it has been up before: https://github.com/netlify/netlify-cms/issues/1320

[erquhart]

Well that took a few hours to debug - mostly because I assumed our code was the problem, but it turned out to be a Git thing. You found an issue that has _always_ existed in this project, but that I've never heard reported. I'll share what I learned today in case anyone else can benefit from it.

tl;dr

If you have a branch named cms, rename it or remove it.

Nested refs in Git

If you create a branch in Git named "foo", Git creates a file by that name in the .git directory of your local repository. Branches are basically refs, and they're placed in the refs/heads directory:

.git
└── refs
    └── heads
        └── foo

That foo is a text file containing the sha for whatever your branch is pointing at.

But Git also supports nesting refs by interpreting branch names with slashes as paths. If your branch is named foo/bar instead of foo, for example, you'll get this:

.git
└── refs
    └── heads
        └── foo
            └── bar

You'll notice that foo is now a directory instead of a file, and the text file is now in bar. You could create as many foo/ prefixed branches as you like and they would all be placed in the foo directory. But of course, this means you can't have a branch named just plain foo, because a directory by that name already exists under refs/heads.

You can have foo, or you can have foo/bar, but you can't have both.

Nested refs in Netlify CMS editorial workflow

When you create an entry in the editorial workflow, Netlify CMS creates a new branch in your repository. The name of that new branch is always prefixed with - you guessed it - cms/, so the resulting branch structure looks like this:

.git
└── refs
    └── heads
        └── cms
            ├── sluggified-post-title
            ├── another-sluggified-post-title
            ...

If you tried to create a branch named cms with this structure in place, Git would error out. Transversely, if you already have a branch named cms and then try to create editorial workflow branches, Git will likewise error out, which is what's happening in this bug report.

Short term solution

If you remove or rename your manually created cms branch to something else, the issue will resolve.

For the project itself, the short term solution is to detect whether a repo has a branch that might cause a conflict like this and at least provide a notification and fail gracefully. The editorial workflow Git functionality is inside of the GitHub backend, so any such check would have to occur there.

This is also a pretty rare bug, so not a high priority.

Long term solution

(This is for the CMS project itself, not developers using it):

Stop 👏🏼 hacky 👏🏼 metadata 👏🏼 solutions 👏🏼

We shouldn't be relying on the branch name to determine if a branch is in the editorial workflow. This and other hacky metadata practices are targeted in #1669, which outlines what I expect to be our final solution to this issue.

Alternate prefixes

I'm guessing someone will suggest that we allow the branch prefix to be configurable, but we tried that a while back as a feature and things did not go well. We reverted. I don't expect we'll be trying that approach again.

[jschill]

@erquhart Thanks a bunch for looking into this - and great work tracking that one down, I would never had find it.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ewlsh]

I think this also applies if you have a branch named netlify. I was struggling to get the CMS working and couldn't figure out why for the life of me (kept getting API not found errors). I eventually found another issue (I'll try to find which one) which said the author just made a new branch and magically all the errors went away - so I tried that. I switched my netlify branch to a cms branch which of course led me here. I deleted the cms branch which fixed the e.filter error but I was back to my prior errors. Finally, I switched everything to an admin branch and deleted the netlify branch.

Everything instantly worked!

Could a list of branches we should _avoid_ be added to the docs? This would have saved me a lot of trouble.

[erezrokah]

Closing as https://github.com/netlify/netlify-cms/pull/3879 will result in a proper error message when this happens