Naming Convention

This guide covers best practices for naming repositories with dot notation.

Basic Syntax

Use dots (.) to separate hierarchy levels:

<domain>.<subdomain>.<name>

Examples:

• auth.service - Authentication service
• auth.oauth.google - Google OAuth implementation
• api.v2.users - Users API version 2

Recommended Patterns

By Domain

Group repositories by business domain:

billing.service
billing.webhook
billing.reports

users.service
users.auth
users.profile

By Layer

Group by architectural layer:

core.database
core.cache
core.queue

api.gateway
api.rest
api.graphql

web.dashboard
web.landing
web.docs

By Feature

Group by feature or product:

checkout.cart
checkout.payment
checkout.shipping

search.indexer
search.query
search.suggest

Naming Guidelines

Do

• Use lowercase letters
• Use singular nouns when possible (user not users)
• Keep names concise but descriptive
• Be consistent across your organization

Don't

• Don't use hyphens for hierarchy (use dots)
• Don't exceed 4 levels of nesting
• Don't mix naming patterns inconsistently

Versioning in Names

For versioned APIs or breaking changes:

api.v1.users
api.v2.users

Or use branches/tags for versioning and keep names clean:

api.users  (with tags: v1.0.0, v2.0.0)

Migration from Existing Repos

If you have existing repositories:

Before	After
auth-service	auth.service
user-api-v2	api.v2.users
frontend-dashboard	web.dashboard

GitDot will automatically recognize the new dot-notation structure.

Platform Considerations

GitHub

GitHub allows dots in repository names. No special configuration needed.

GitLab

GitLab supports both subgroups and dot notation. You can:

• Use native subgroups for top-level organization
• Use dot notation within subgroups for additional hierarchy

Gitea

Gitea allows dots in repository names. Works identically to GitHub.