이 지침은 glab CLI 레퍼런스 문서에 필요한 구조·내용·언어 규칙을 정의합니다.

다음 작업을 할 때 이 지침을 사용합니다.

• gitlab-org/cli에 새 glab 명령을 추가할 때.
• CLI 문서가 되는 Go 소스 문자열을 업데이트할 때.
• CLI 문서를 추가하거나 변경하는 머지 리퀘스트를 검토할 때.

이 지침이 문서 스타일 가이드와 다르면, 페이지 구조·Synopsis 문구· 플래그 설명·사용 중단 메시지처럼 CLI 고유의 내용에 대해서는 이 페이지를 따릅니다.

대문자 표기·태(voice)·일반 용어처럼 여기서 다루지 않는 규칙은 문서 스타일 가이드를 따릅니다.

CLI 문서 생성 방식#

CLI 문서는 gitlab-org/cli의 Go 소스 파일에서 생성됩니다. 생성기(make gen-docs)는 명령마다 Markdown 파일 하나를 만들어 docs/source/에 출력합니다. 생성된 파일이 GitLab CLI(glab) 문서의 정본입니다.

생성 결과에 영향을 주는 Go 소스 문자열을 변경하면 make gen-docs를 실행하고 갱신된 파일을 머지 리퀘스트에 함께 커밋합니다. check_docs_update CI/CD job은 make gen-docs를 실행하고, 생성된 파일에 커밋되지 않은 변경이 있으면 실패합니다.

커밋을 푸시하기 전에 문서 문제를 잡으려면 make bootstrap을 실행해 Lefthook을 설치합니다. pre-commit 훅은 명령 파일이 바뀌면 문서를 다시 생성하고, 갱신된 파일이 스테이징될 때까지 커밋을 막습니다. 자세한 내용은 Lefthook을 사용한 Git 훅을 참고합니다.

페이지 구조#

생성되는 모든 CLI 문서 페이지에는 다음 섹션이 이 순서대로 있어야 합니다.

1. 제목(Title)
2. 짧은 설명(Short description)
3. 개요(Synopsis)
4. 별칭(Aliases) — 명령에 별칭이 있는 경우
5. 예시(Examples)
6. 옵션(Options)
7. 상위 명령에서 상속된 옵션(Options inherited from parent commands)
8. 하위 명령(Subcommands) — 명령에 하위 명령이 있는 경우

다음 표는 각 페이지 섹션과 이를 생성하는 Go 소스 필드의 대응 관계를 보여 줍니다.

제목(Title)#

제목은 전체 명령 호출을 인라인 코드로 표기한 것입니다. 예를 들면 다음과 같습니다.

title: '`glab mr create`'

제목은 Go 소스의 명령 이름에서 생성됩니다. 직접 편집하지 않습니다.

짧은 설명(Short description)#

짧은 설명은 Go 명령 정의의 Short 필드에서 생성됩니다. 명령이 하는 일을 설명하는 한 문장입니다.

• 명령형으로 작성합니다. 예: Create a new merge request.
• 제목을 그대로 반복하지 않습니다.
• 마침표로 끝냅니다.
• 실험 단계 명령에는 문장 뒤에 (EXPERIMENTAL)을 붙입니다. 예: Create a new stacked diff. (EXPERIMENTAL)

개요(Synopsis)#

모든 새 명령에는 Synopsis가 있어야 합니다. Synopsis는 Go 명령 정의의 Long 필드에서 생성되며, 짧은 설명에 담을 수 없는 추가 컨텍스트를 제공합니다. 예를 들어 명령이 다음에 해당하는 경우입니다.

• 사용 제약이 있거나 상호 배타적인 플래그가 있습니다.
• 타입이 지정된 입력이나 특수한 입력 형식을 받습니다.
• 컨텍스트에 따라 동작이 달라집니다(예: 브랜치 파이프라인과 머지 리퀘스트 파이프라인).
• 최소 GitLab 버전이 필요합니다. 자세한 내용은 버전 지원을 참고합니다.
• 실험 단계입니다.

제약이나 입력 타입이 여러 개면 목록을 사용합니다. 짧은 설명에 이미 있는 정보는 반복하지 않습니다.

사용법 줄 규칙#

사용법 줄은 Synopsis 섹션과 --help 출력에 나타납니다. 위치 인수에는 다음 규칙을 사용합니다.

실험 기능과 베타 기능#

아직 프로덕션에서 사용할 준비가 되지 않은 기능을 표시하기 위해 internal/text/text.go에 상수 두 개가 정의돼 있습니다.

• text.ExperimentalString: 실험 단계 기능에 사용합니다.
• text.BetaString: 베타 단계 기능에 사용합니다.

Long 필드에 text.ExperimentalString 또는 text.BetaString을 덧붙입니다. 올바른 패턴은 Long 필드를 정의한 방식에 따라 달라집니다.

• 문자열 연결을 사용하는 heredoc.Doc 또는 heredoc.Docf: 두 함수 모두 템플릿의 뒤쪽 공백을 제거하므로 ExperimentalString이 가진 선행 줄바꿈이 구분자 역할을 합니다. 별도의 "\n"은 필요하지 않습니다.

  Long: heredoc.Doc(`
      Your command description here.
  `) + text.ExperimentalString,
  

• %s 자리 표시자를 쓰는 heredoc.Docf: 상수를 형식 인수로 전달합니다. 상수의 선행 줄바꿈이 구분자 역할을 합니다.

  Long: heredoc.Docf(`
      Your command description here.
      %s`, text.ExperimentalString),
  

• 원시 문자열 리터럴: 리터럴은 공백이 제거되지 않으므로, 닫는 백틱 앞에 줄바꿈을 명시적으로 넣습니다.

  var longString = `Your command description here.
  ` + text.ExperimentalString
  

  원시 문자열이 줄바꿈으로 끝나지 않으면 "\n" 구분자를 명시적으로 추가합니다.

  Long: `Your command description here.` + "\n" + text.ExperimentalString,
  

이렇게 하면 생성된 문서의 Synopsis 섹션에 다음 문구가 나타납니다.

This feature is an experiment and is not ready for production use.
It might be unstable or removed at any time.
For more information, see
https://docs.gitlab.com/policy/development_stages_support/.

베타 명령에는 text.BetaString을 같은 방식으로 사용합니다. 결과는 다음과 같습니다.

This feature is in beta and might not be ready for production use.
It might be unstable and breaking changes can occur outside of major releases.
For more information, see
https://docs.gitlab.com/policy/development_stages_support/.

이 문자열을 Long 필드에 직접 복사하지 않습니다. 문구가 나중에 바뀌어도 모든 명령에 일관되게 반영되도록 항상 상수를 사용합니다.

명령 전체가 아니라 개별 플래그만 실험 단계이면 이를 알리는 짧은 설명을 Synopsis에 추가합니다. 예를 들면 다음과 같습니다.

The --publish-to-catalog flag is experimental and requires the
`ci_release_cli_catalog_publish_option` feature flag to be enabled for your project.

기능에 기능 플래그 활성화가 필요하면 그 요구 사항을 Synopsis에 기재합니다.

실험 기능 수명 주기#

실험 기능은 호환성 변경 없이 수정하거나 제거할 수 있습니다. 기능이 실험 단계에서 일반 공급(GA)으로 전환되면 다음을 수행합니다.

1. 짧은 설명에서 (EXPERIMENTAL)을 제거합니다.
2. Long 필드에서 text.ExperimentalString(또는 text.BetaString)을 제거합니다.
3. 모든 플래그 설명에서 (EXPERIMENTAL)을 제거합니다.
4. make gen-docs를 실행하고 갱신된 파일을 커밋합니다.

별칭(Aliases)#

명령의 별칭을 나열합니다. 이 섹션은 Go 명령 정의의 Aliases 필드에서 자동으로 생성됩니다. 직접 편집하지 않습니다.

예시(Examples)#

Examples 섹션은 Go 명령 정의의 Example 필드에서 생성됩니다. 모든 명령에는 실제 사용 사례를 보여 주는 예시가 최소 하나 있어야 합니다. 사용법 줄을 그대로 반복하기만 하는 예시는 사용하지 않습니다.

• 사용 사례별로 예시를 묶습니다.

• 의미가 바로 드러나지 않는 예시에는 명령 위 줄에 # Comment text 형식으로 인라인 주석을 답니다. 다음 중 하나에 해당하면 의미가 바로 드러나지 않는 예시입니다.

  • 플래그 설명만으로는 파악하기 어려운 방식으로 여러 플래그를 조합합니다.
  • Options 섹션에 없는 값 형식을 사용합니다. 예를 들어 특정 날짜 형식이나 ID 패턴이 있습니다.
  • 현재 브랜치나 리포지터리 상태처럼 컨텍스트에 따라 결과가 달라집니다.

• 옵션이 많은 명령은 가장 흔한 조합을 먼저 보여 줍니다.

예를 들면 다음과 같습니다.

# Create a merge request and assign it to yourself
glab mr create -a @me -t "Fix the login bug"

# Create a draft merge request from the current branch
glab mr create --draft --fill

옵션(Options)#

Options 섹션에는 해당 명령에만 적용되는 모든 플래그가 나열됩니다. 이 섹션은 Go 소스의 플래그 정의에서 생성됩니다.

플래그는 Go 소스(cmd.Flags()와 cmd.PersistentFlags())에 등록된 순서대로 나타납니다. 생성된 Markdown 출력에서 직접 순서를 바꾸지 않습니다.

Go 소스에 플래그 설명을 작성할 때는 다음 규칙을 따릅니다.

• 대문자로 시작합니다.

• 마침표로 끝냅니다.

• 사용자가 입력하는 값에는 꺾쇠 괄호 자리 표시자를 사용합니다. 예: <username>, <branch>.

• 기본값이 true인 불리언 플래그에는 pflag가 생성된 Markdown 출력에 (default true)를 자동으로 붙입니다. 직접 추가하지 않습니다. 기본값이 false인 불리언 플래그에는 기본값 표기가 필요하지 않습니다.

• 일반적인 값 타입에는 표준 메타 변수를 사용합니다.

  값 타입	메타 변수
  사용자 이름	username
  브랜치 이름	string
  파일 경로	string
  정수 ID	int
  출력 형식	string

• 출력 형식 플래그에는 -F, --output [text | json]을 표준 형태로 사용합니다. 같은 명령 안의 다른 플래그와 이름이 충돌해 다른 짧은 플래그를 쓰는 명령도 있습니다.

실험 단계 플래그#

플래그가 실험 단계이면 설명 앞에 (EXPERIMENTAL)을 붙입니다. 예를 들면 다음과 같습니다.

--publish-to-catalog    (EXPERIMENTAL) Publish the release to the GitLab CI/CD catalog.

실험 상태와 기능 플래그 요구 사항을 설명하는 Synopsis 안내도 추가합니다. 자세한 내용은 실험 기능과 베타 기능을 참고합니다.

상위 명령에서 상속된 옵션#

이 섹션에는 --help나 --repo처럼 한 그룹의 모든 하위 명령에서 쓸 수 있는 플래그가 나열됩니다. 상위 명령의 상속 플래그에서 자동으로 생성되므로 직접 편집하지 않습니다. 상속 플래그를 변경하려면 상위 명령의 Go 소스를 수정해야 합니다.

하위 명령(Subcommands)#

Subcommands 섹션은 상위 명령 인덱스 페이지(_index.md)에만 나타납니다. 예를 들어 glab ci와 glab mr 페이지가 있습니다. 이 섹션은 각 하위 명령 페이지로 연결되는 불릿 목록으로 자동 생성됩니다. 직접 편집하지 않습니다.

머지 리퀘스트 제목#

MR 제목은 commit-lint CI job이 검증합니다. 머지 시 스쿼시가 기본으로 활성화돼 있어, MR을 머지하면 MR 제목이 커밋 메시지가 됩니다. 제목은 프로젝트 기여 가이드라인에 정의된 conventional commits 형식을 따라야 합니다.

Front matter#

생성되는 모든 페이지에는 front matter가 포함됩니다. stage와 group 값은 생성기(cmd/gen-docs/docs.go)에 모든 명령에 대해 AI Coding과 Code Review로 하드코딩돼 있습니다. 생성된 파일에서 이 값을 편집하지 않습니다. make gen-docs를 실행할 때마다 덮어써집니다.

환경 변수#

glab 동작에 영향을 주는 모든 환경 변수의 정본 레퍼런스는 구성 페이지의 환경 변수 섹션입니다. 이 레퍼런스에는 GitLab 액세스 변수(GITLAB_TOKEN, GITLAB_HOST 등), glab 구성 변수(BROWSER, GLAB_NO_PROMPT, GLAB_GLAMOUR_STYLE 등), 그리고 이에 대응하는 config.yml 키와 기본값이 정리돼 있습니다.

이 표는 internal/config/schema.go의 KeySchema에서 생성되어 docs/source/configuration.md의 센티널 주석 사이에 기록됩니다. 구성 키를 거치지 않고 glab이 직접 읽는 변수는 internal/config/envvars.go의 nonSchemaEnvVars에 나열돼 있습니다. 변수를 추가하거나 변경하려면 Go 소스를 편집하고 make gen-docs를 실행합니다. 생성된 표를 직접 편집하지 않습니다.

루트 명령 페이지는 이 레퍼런스로 연결되며 변수를 반복하지 않습니다. 개별 명령 페이지에 전체 변수 목록을 중복해 싣지 않습니다.

특정 명령의 동작이 환경 변수의 영향을 받는 경우에는 Synopsis에서 그 변수를 언급합니다. 변수를 인라인 코드로 적고, 그 명령에서 어떤 영향을 주는지 설명을 덧붙입니다. 예를 들면 다음과 같습니다.

If `GITLAB_TOKEN`, `GITLAB_ACCESS_TOKEN`, or `OAUTH_TOKEN` are set,
they take precedence over the stored credentials.

사용 중단 지침은 사용 중단된 환경 변수를 참고합니다.

사용 중단#

glab에서 플래그·명령·환경 변수를 사용 중단할 때는 다음 지침을 따릅니다.

사용 중단된 플래그#

MarkDeprecated로 플래그를 사용 중단하면 Cobra가 메시지 앞에 고정 접두사를 붙입니다.

Flag --<flag> has been deprecated, <your message>

Cobra의 접두사는 쉼표로 끝납니다. 메시지는 문장을 이어 가는 형태로 소문자로 시작해 마침표로 끝냅니다. 예를 들어 use --output instead.는 다음과 같이 출력됩니다.

Flag --output-format has been deprecated, use --output instead.

사용 중단된 플래그에 바로 대체할 항목이 있으면 메시지를 use --<replacement> instead.로 끝냅니다. 대체 항목이 없으면 그 결과 동작을 설명합니다. 예를 들면 tracking is enabled by default.입니다.

사용 중단 메시지에는 now나 currently처럼 시점에 의존하는 표현을 쓰지 않습니다.

이 규칙은 REST API 사용 중단 지침을 Cobra 래퍼에 맞춰 적용한 것입니다.

사용 중단된 명령#

명령을 사용 중단하려면 해당 cobra.Command의 Deprecated 필드에 대체 항목을 알려 주는 메시지를 설정합니다. Cobra가 메시지 앞에 고정 접두사를 붙입니다.

Command "<command>" is deprecated, <your message>

사용 중단된 플래그와 마찬가지로 메시지는 문장을 이어 가는 형태로 소문자로 시작해 마침표로 끝냅니다. 명령에 바로 대체할 항목이 있으면 그 이름을 적습니다. 예를 들어 use `glab mr create --related-issue <issueID>`.는 다음과 같이 출력됩니다.

Command "for" is deprecated, use `glab mr create --related-issue <issueID>`.

Cobra는 사용자가 명령을 실행할 때 CLI에 이 메시지를 출력하므로, 사용자는 컨텍스트 안에서 이전 경로를 확인합니다. 문서에 별도의 사용 중단 안내를 추가하지 않습니다. 사용 중단된 명령은 숨김 명령과 같이 처리되어 생성된 페이지에서 제외됩니다. make gen-docs를 실행하면 해당 명령의 페이지가 정리되고, 내비게이션이나 상위 명령 목록에도 더 이상 표시되지 않습니다. 삭제된 페이지를 머지 리퀘스트에 함께 커밋합니다.

사용 중단된 환경 변수#

환경 변수를 사용 중단할 때는 internal/config/schema.go의 해당 KeyDef를 업데이트합니다. EnvVars 필드는 구성 페이지와 사용자가 glab config --help를 실행할 때 표시되는 변수 목록의 단일 출처이므로, 한 번만 변경하면 이름이 나타나는 모든 곳에 반영됩니다.

1. EnvVars 필드에서 사용 중단된 이름을 제거합니다.
2. EnvVars에 대체 이름을 추가합니다. 목록의 첫 번째 이름이 우선합니다.
3. 변경이 동작에 영향을 주면 Description 필드를 업데이트합니다.
4. make gen-docs를 실행하고 다시 생성된 파일을 커밋합니다.

glab이 직접 읽는 변수는 대신 internal/config/envvars.go의 nonSchemaEnvVars에서 해당 항목을 업데이트합니다.

버전 지원#

glab은 공식적으로 GitLab 16.0 이상을 지원합니다. 명령이나 플래그가 올바르게 동작하는 데 더 최신 GitLab 버전이 필요하면, 그 요구 사항을 Synopsis에 기재합니다. 예를 들면 다음과 같습니다.

This command requires GitLab 17.0 or later.

명령이나 플래그가 특정 glab 버전을 요구하면 같은 방식으로 Synopsis에 기재합니다. 예를 들면 다음과 같습니다.

This flag requires glab 1.50.0 or later.

기능에 glab 버전 요구 사항과 GitLab 서버 버전 요구 사항이 모두 있으면 둘 다 기재합니다.

버전 관리와 호환성 변경#

glab은 SemVer를 따릅니다. 이 버전 관리 규칙은 명령과 플래그를 문서화하는 방식에 직접 영향을 줍니다.

관련 주제#

• 문서 스타일 가이드
• GitLab CLI(glab) 문서
• REST API 리소스 문서화
• gitlab-org/cli README
• CONTRIBUTING.md