Docs
Gemini CLI 사용하기
파일 관리

Gemini CLI 파일 시스템 도구

Gemini CLI는 로컬 파일 시스템과 상호 작용하기 위한 포괄적인 도구 모음을 제공합니다. 이 도구들을 사용하면 Gemini 모델이 파일과 디렉토리를 읽고, 쓰고, 나열하고, 검색하고, 수정할 수 있으며, 이 모든 작업은 사용자의 제어하에 수행되며 일반적으로 민감한 작업에 대해서는 확인을 거칩니다.

참고: 모든 파일 시스템 도구는 보안을 위해 rootDirectory(일반적으로 CLI를 실행한 현재 작업 디렉토리) 내에서 작동합니다. 이러한 도구에 제공하는 경로는 일반적으로 절대 경로이거나 이 루트 디렉토리를 기준으로 해결됩니다.

1. list_directory (ReadFolder)

list_directory는 지정된 디렉토리 경로 내에 있는 파일 및 하위 디렉토리의 이름을 직접 나열합니다. 선택적으로 제공된 glob 패턴과 일치하는 항목을 무시할 수 있습니다.

  • 도구 이름: list_directory
  • 표시 이름: ReadFolder
  • 파일: ls.ts
  • 매개변수:
    • path (string, 필수): 나열할 디렉토리의 절대 경로입니다.
    • ignore (array of strings, 선택): 나열에서 제외할 glob 패턴 목록입니다 (예: ["*.log", ".git"]).
    • respect_git_ignore (boolean, 선택): 파일을 나열할 때 .gitignore 패턴을 준수할지 여부입니다. 기본값은 true입니다.
  • 동작:
    • 파일 및 디렉토리 이름 목록을 반환합니다.
    • 각 항목이 디렉토리인지 여부를 나타냅니다.
    • 디렉토리를 먼저 정렬한 다음 알파벳순으로 항목을 정렬합니다.
  • 출력 (llmContent): 다음과 같은 문자열: Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png
  • 확인: 아니요.

2. read_file (ReadFile)

read_file은 지정된 파일의 내용을 읽고 반환합니다. 이 도구는 텍스트, 이미지 (PNG, JPG, GIF, WEBP, SVG, BMP), 오디오 파일 (MP3, WAV, AIFF, AAC, OGG, FLAC) 및 PDF 파일을 처리합니다. 텍스트 파일의 경우 특정 줄 범위를 읽을 수 있습니다. 다른 이진 파일 유형은 일반적으로 건너뜁니다.

  • 도구 이름: read_file
  • 표시 이름: ReadFile
  • 파일: read-file.ts
  • 매개변수:
    • path (string, 필수): 읽을 파일의 절대 경로입니다.
    • offset (number, 선택): 텍스트 파일의 경우 0부터 시작하는 줄 번호로, 읽기를 시작할 위치입니다. limit 설정이 필요합니다.
    • limit (number, 선택): 텍스트 파일의 경우 읽을 최대 줄 수입니다. 생략하면 기본 최대값 (예: 2000줄) 또는 가능한 경우 전체 파일을 읽습니다.
  • 동작:
    • 텍스트 파일의 경우: 내용을 반환합니다. offset과 limit를 사용하면 해당 줄 범위만 반환합니다. 줄 제한이나 줄 길이 제한으로 인해 내용이 잘린 경우 이를 나타냅니다.
    • 이미지, 오디오 및 PDF 파일의 경우: 모델이 소비하기에 적합한 base64로 인코딩된 데이터 구조로 파일 내용을 반환합니다.
    • 기타 이진 파일의 경우: 이를 식별하고 건너뛰려고 시도하며 일반 이진 파일임을 나타내는 메시지를 반환합니다.
  • 출력 (llmContent):
    • 텍스트 파일의 경우: 파일 내용, 잠재적으로 잘림 메시지가 앞에 붙습니다 (예: [File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...).
    • 이미지/오디오/PDF 파일의 경우: mimeType 및 base64 data를 포함하는 inlineData 객체입니다 (예: { inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }).
    • 기타 이진 파일의 경우: 다음과 같은 메시지 Cannot display content of binary file: /path/to/data.bin.
  • 확인: 아니요.

3. write_file (WriteFile)

write_file은 지정된 파일에 내용을 씁니다. 파일이 존재하면 덮어씁니다. 파일이 존재하지 않으면 파일 (및 필요한 상위 디렉토리)을 생성합니다.

  • 도구 이름: write_file
  • 표시 이름: WriteFile
  • 파일: write-file.ts
  • 매개변수:
    • file_path (string, 필수): 쓸 파일의 절대 경로입니다.
    • content (string, 필수): 파일에 쓸 내용입니다.
  • 동작:
    • file_path에 제공된 content를 씁니다.
    • 상위 디렉토리가 존재하지 않으면 생성합니다.
  • 출력 (llmContent): 성공 메시지, 예: Successfully overwrote file: /path/to/your/file.txt 또는 Successfully created and wrote to new file: /path/to/new/file.txt.
  • 확인: 예. 변경 사항의 diff를 표시하고 쓰기 전에 사용자 승인을 요청합니다.

4. glob (FindFiles)

glob finds files matching specific glob patterns (e.g., src/**/*.ts, *.md), 수정 시간순(최신순)으로 정렬된 절대 경로를 반환합니다.

  • 도구 이름: glob

  • 표시 이름: FindFiles

  • 파일: glob.ts

  • 매개변수:

    • pattern (string, 필수): 파일을 찾기 위한 glob 패턴입니다 (예: src/**/*.ts).
    • path (string, 선택): 검색할 디렉토리의 절대 경로입니다. 기본값은 현재 작업 디렉토리입니다.
    • ignore (array of strings, 선택): 목록에서 제외할 glob 패턴 목록입니다 (예: ["*.log", ".git"]).
    • case_sensitive (boolean, 선택): glob 매칭이 대소문자를 구분할지 여부입니다. 기본값은 false입니다.
    • respect_git_ignore (boolean, 선택): 파일을 찾을 때 .gitignore 패턴을 준수할지 여부입니다. 기본값은 true입니다.

  • 동작:

    • 지정된 디렉토리 내에서 glob 패턴과 일치하는 파일을 검색합니다.
    • 가장 최근에 수정된 파일이 먼저 오도록 정렬된 절대 경로 목록을 반환합니다.
    • 기본적으로 node_modules 및 .git과 같은 일반적인 불필요한 디렉토리는 무시합니다.

  • 출력 (llmContent): 다음과 같은 메시지: Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...

  • 확인: 아니요.

5. grep_search (SearchText)

grep_search는 지정된 디렉토리의 파일 내용에서 정규식 패턴을 검색합니다. glob 패턴으로 파일을 필터링할 수 있습니다. 일치하는 항목이 포함된 줄을 파일 경로 및 줄 번호와 함께 반환합니다.

  • 도구 이름: grep_search
  • 표시 이름: SearchText
  • 파일: grep.ts
  • 매개변수:
    • pattern (string, 필수): 검색할 정규 표현식 (regex)입니다 (예: "function\s+myFunction").
    • path (string, 선택): 검색할 디렉토리의 절대 경로입니다. 기본값은 현재 작업 디렉토리입니다.
    • include (string, 선택): 검색할 파일을 필터링하는 glob 패턴입니다 (예: "*.js", "src/**/*.{ts,tsx}"). 생략하면 대부분의 파일을 검색합니다 (일반적인 무시 항목 준수).
  • 동작:
    • Git 저장소에서 사용 가능한 경우 속도를 위해 git grep을 사용합니다; 그렇지 않으면 시스템 grep 또는 JavaScript 기반 검색으로 대체합니다.
    • 일치하는 줄 목록을 반환하며, 각 줄에는 파일 경로 (검색 디렉토리 기준)와 줄 번호가 접두사로 붙습니다.
  • 출력 (llmContent): 다음과 같이 포맷된 일치 항목 문자열: 
    Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
---
File: src/utils.ts
L15: export function myFunction() {
L22:   myFunction.call();
---
File: src/index.ts
L5: import { myFunction } from './utils';
---
  • 확인: 아니요.

6. replace (Edit)

replace는 파일 내의 텍스트를 바꿉니다. 기본적으로 단일 항목을 대체하지만, expected_replacements가 지정되면 여러 항목을 대체할 수 있습니다. 이 도구는 정확하고 대상이 지정된 변경을 위해 설계되었으며 올바른 위치를 수정하도록 보장하기 위해 old_string 주위에 상당한 컨텍스트가 필요합니다.

  • 도구 이름: replace

  • 표시 이름: Edit

  • 파일: edit.ts

  • 매개변수:

    • file_path (string, 필수): 수정할 파일의 절대 경로입니다.

    • old_string (string, 필수): 대체할 정확한 리터럴 텍스트입니다.

      중요: 이 문자열은 변경할 단일 인스턴스를 고유하게 식별해야 합니다. 대상 텍스트 이전과 이후에 최소 3줄의 컨텍스트를 포함해야 하며, 공백과 들여쓰기가 정확하게 일치해야 합니다. old_string이 비어 있으면 도구는 file_path에 new_string을 내용으로 하는 새 파일을 생성하려고 시도합니다.

    • new_string (string, 필수): old_string을 대체할 정확한 리터럴 텍스트입니다.

    • expected_replacements (number, 선택): 대체할 발생 횟수입니다. 기본값은 1입니다.

  • 동작:

    • old_string이 비어 있고 file_path가 존재하지 않으면 new_string을 내용으로 하는 새 파일을 생성합니다.
    • old_string이 제공되면 file_path를 읽고 old_string의 정확히 하나 발생을 찾으려고 시도합니다.
    • 하나의 발생이 발견되면 new_string으로 대체합니다.
    • 향상된 신뢰성 (다단계 편집 수정): 특히 모델이 제공한 old_string이 완벽하게 정확하지 않을 때 편집 성공률을 크게 향상시키기 위해 도구는 다단계 편집 수정 메커니즘을 통합합니다.
      • 초기 old_string을 찾을 수 없거나 여러 위치와 일치하는 경우 도구는 Gemini 모델을 활용하여 old_string (및 잠재적으로 new_string)을 반복적으로 구체화할 수 있습니다.
      • 이 자체 수정 프로세스는 모델이 수정하려는 고유한 세그먼트를 식별하려고 시도하여 약간 불완전한 초기 컨텍스트에서도 replace 작업을 더 견고하게 만듭니다.

  • 실패 조건: 수정 메커니즘에도 불구하고 다음과 같은 경우 도구가 실패합니다:

    • file_path가 절대 경로가 아니거나 루트 디렉토리 외부에 있는 경우.
    • old_string이 비어 있지 않지만 file_path가 존재하지 않는 경우.
    • old_string이 비어 있지만 file_path가 이미 존재하는 경우.
    • 수정 시도 후에도 파일에서 old_string을 찾을 수 없는 경우.
    • old_string이 여러 번 발견되고 자체 수정 메커니즘이 단일하고 명확한 일치 항목으로 해결할 수 없는 경우.

  • 출력 (llmContent):

    • 성공 시: Successfully modified file: /path/to/file.txt (1 replacements). 또는 Created new file: /path/to/new_file.txt with provided content.
    • 실패 시: 이유를 설명하는 오류 메시지 (예: Failed to edit, 0 occurrences found..., Failed to edit, expected 1 occurrences but found 2...).

  • 확인: 예. 제안된 변경 사항의 diff를 표시하고 파일에 쓰기 전에 사용자 승인을 요청합니다.

이러한 파일 시스템 도구는 Gemini CLI가 로컬 프로젝트 컨텍스트를 이해하고 상호 작용할 수 있는 기반을 제공합니다.

CLI 사용법셸 명령