{"record":{"id":"12e80647be931b7b","repo":"abhigyanpatwari/GitNexus","slug":"contains-characters-not-allowed-in-a-git-ref","errorCode":null,"errorMessage":"contains characters not allowed in a git ref","messagePattern":"contains characters not allowed in a git ref","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/auto-sync/config.ts","lineNumber":338,"sourceCode":"  if (\n    !repoName ||\n    repoName === '.' ||\n    repoName === '..' ||\n    repoName === 'unknown' ||\n    repoName.startsWith('-') ||\n    !REMOTE_REPO_NAME_PATTERN.test(repoName)\n  ) {\n    throw new Error(\n      'repository name must use only letters, digits, \".\", \"_\", or \"-\" and must not be \"unknown\"',\n    );\n  }\n}\n\nexport function validateAutoSyncBranchName(branch: string): void {\n  if (!branch.trim()) throw new Error('must not be empty');\n  if (/[\\s\\0-\\x1f\\x7f]/.test(branch))\n    throw new Error('must not contain whitespace or control characters');\n  if (/[~^:?*[\\\\]/.test(branch)) throw new Error('contains characters not allowed in a git ref');\n  if (branch.startsWith('-')) throw new Error('must not start with \"-\"');\n  if (branch.startsWith('/')) throw new Error('must not start with \"/\"');\n  if (branch.includes('..')) throw new Error('must not contain \"..\"');\n  if (branch.includes('`')) throw new Error('must not contain backticks');\n  if (branch.endsWith('/') || branch.endsWith('.')) throw new Error('must not end with \"/\" or \".\"');\n  if (branch.includes('//')) throw new Error('must not contain consecutive slashes');\n  if (branch.includes('@{')) throw new Error('must not contain \"@{\"');\n  if (\n    branch\n      .split('/')\n      .some(\n        (component) =>\n          component.startsWith('.') || component.endsWith('.') || component.endsWith('.lock'),\n      )\n  )\n    throw new Error('must not contain hidden, trailing-dot, or .lock path components');\n}\n","sourceCodeStart":320,"sourceCodeEnd":356,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/0d1aed942f0e8b5d3bac27519fff441aceea722d/gitnexus/src/core/auto-sync/config.ts#L320-L356","documentation":"Git ref syntax forbids several characters, so validateAutoSyncBranchName rejects branches containing any of ~ ^ : ? * [ \\ before a git command is ever run. These characters would make the ref unresolvable or trigger glob/history syntax inside git, so the library fails at config parse time.","triggerScenarios":"branches: [\"feature:foo\"], [\"v1.0^\"], [\"release~2\"], [\"topic?\"], [\"fix[bug]\"], or a Windows-style path like \"feature\\\\login\" in the auto-sync config.","commonSituations":"Copy-pasted tags with ^ or ~ suffixes (v1.2^ means 'parent of v1.2', not a branch); Windows users writing backslash-separated paths; query strings appended to branch names from URLs.","solutions":["Use the plain branch/ref name without git revision syntax — drop ^, ~, :suffix.","Replace backslashes with forward slashes for nested branch names: feature\\\\login → feature/login.","If you meant a specific commit, configure the branch it lives on, not a revision expression.","Validate locally with `git check-ref-format --branch '<name>'` before adding it to config."],"exampleFix":"// before\nbranches:\n  - \"release~2\"\n// after\nbranches:\n  - release","handlingStrategy":"validation","validationCode":"const GIT_REF_BAD = /[~^:?*[\\\\]/;\nfunction refCharsOk(b) {\n  return typeof b === 'string' && !GIT_REF_BAD.test(b);\n}\nconst bad = (cfg.branches ?? []).filter((b) => !refCharsOk(b));\nif (bad.length) throw new Error(`branches contain git-ref-forbidden characters: ${JSON.stringify(bad)}`);","typeGuard":null,"tryCatchPattern":"try {\n  validateAutoSyncBranchName(branch);\n} catch (e) {\n  if (String(e.message).includes('characters not allowed in a git ref')) {\n    log.error(`Branch '${branch}' uses ~^:?*[\\\\ which git refs forbid; use the plain branch name.`);\n  }\n  throw e;\n}","preventionTips":["Run `git check-ref-format --branch <name>` before adding a branch to config.","Never paste revision expressions (~, ^) or globs (*, ?) as branch names.","Use forward slashes, not backslashes, for nested branch names."],"tags":["config","git","branch","ref-syntax","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"0d1aed942f0e8b5d3bac27519fff441aceea722d","analyzedAt":"2026-09-08T00:40:44.970Z","contentChangedAt":"2026-09-08T00:40:44.970Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}