.qignore 설정 및 배포 제외 규칙

이 문서에서 배울 내용

  • .qignore 파일 작성 방법 및 패턴 규칙

  • 기본 제외 항목 목록 (.env, .ipynb, __pycache__ 등)

  • 파일 포함 여부 판정 순서

이 문서는 배포 파일을 생성할 때 포함되거나 제외되는 파일의 규칙과 .qignore 파일의 작성 방법을 설명합니다.

.qignore

.qignore는 배포 패키지에서 제외할 파일이나 폴더의 패턴을 직접 정의하는 파일입니다.

  • 위치: 프로젝트 루트 디렉토리 (./.qignore)

  • 형식: 각 줄마다 하나의 패턴을 입력합니다.

  • 주석: #으로 시작하는 줄은 주석으로 처리됩니다.

  • 빈 줄: 내용은 무시됩니다.

  • 패턴 매칭: fnmatch 와일드카드(*, ?)를 사용할 수 있습니다.

작성 예시

# 로그 파일 제외
*.log

# 로컬 시크릿 파일 제외
secrets/*

# 특정 데이터 디렉토리 제외
data/

패턴의 끝이 /인 경우 해당 디렉토리와 내부의 모든 파일이 제외됩니다.

기본 제외 규칙

.qignore 파일을 작성하지 않더라도, 다음 항목들은 기본적으로 배포 대상에서 제외됩니다.

파일명 기준

  • .env로 시작하는 파일 (예: .env, .env.local)

  • db.json

  • .bash로 시작하는 파일

  • .DS_Store

  • .dockerignore, .flake8, .python-version

  • 특정 확장자 파일: .ipynb, .zip, .tar.gz, .log

  • 파일명이 code인 경우

  • 파일명이 qupiato인 경우

경로 및 디렉토리 기준

  • 유효하지 않은 심볼릭 링크(Broken Symbolic Link)

  • 숨김 디렉토리 내부의 파일 (예: .idea/, .cursor/, .vscode/ 등)

  • 디렉토리명이 logs인 경로 내부의 파일

탐색 제외 디렉토리

다음 디렉토리는 파일 탐색 단계에서 탐색하지 않고 건너뜁니다.

  • __pycache__

  • .venv

  • .git

포함 여부 판정 기준

파일의 배포 포함 여부는 다음 순서에 따라 결정됩니다.

  1. 기본 제외 규칙에 해당하면 제외됩니다.

  2. .qignore 패턴과 전체 경로가 일치하면 제외됩니다.

  3. .qignore 패턴과 파일명이 일치하면 제외됩니다.

  4. 위 조건에 해당하지 않는 경우 배포 파일에 포함됩니다.

권장 사용법

  • 팀이나 개발 환경에서 공통으로 제외해야 할 항목은 .qignore에 명시합니다.

  • 민감한 정보(Secrets), 대용량 산출물, 로컬 테스트용 파일은 배포 패키지 용량 최적화와 보안을 위해 제외하는 것을 권장합니다.

  • 배포에 반드시 필요한 파일만 남긴다는 원칙으로 패턴을 관리합니다.

다음 단계