# .qignore 설정 및 배포 제외 규칙

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

## .qignore

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

- **위치**: 프로젝트 루트 디렉토리 (`./.qignore`)
- **형식**: 각 줄마다 하나의 패턴을 입력합니다.
- **주석**: `#`으로 시작하는 줄은 주석으로 처리됩니다.
- **빈 줄**: 내용은 무시됩니다.
- **패턴 매칭**: `fnmatch` 와일드카드(`*`, `?`)를 사용할 수 있습니다.

**작성 예시**

```txt
# 로그 파일 제외
*.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`인 경로 내부의 파일

### 탐색 제외 디렉토리

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

- `__pycache__`
- `.venv`
- `.git`

## 포함 여부 판정 기준

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

1. **기본 제외 규칙**에 해당하면 제외됩니다.
2. `.qignore` 패턴과 **전체 경로**가 일치하면 제외됩니다.
3. `.qignore` 패턴과 **파일명**이 일치하면 제외됩니다.
4. 위 조건에 해당하지 않는 경우 배포 파일에 포함됩니다.

## 권장 사용법

- 팀이나 개발 환경에서 공통으로 제외해야 할 항목은 `.qignore`에 명시합니다.
- 민감한 정보(Secrets), 대용량 산출물, 로컬 테스트용 파일은 배포 패키지 용량 최적화와 보안을 위해 제외하는 것을 권장합니다.
- 배포에 반드시 필요한 파일만 남긴다는 원칙으로 패턴을 관리합니다.