Git REST API 사용 설명서

이 문서는 교육용 서버에서 본인 호스팅 공간의 Git 저장소(repo.git)를 HTTPS REST API로 조작하고 커스텀 버전관리 웹 애플리케이션을 개발하는 방법을 설명합니다. 교육생·강사·관리자 로그인 세션을 기반으로 본인 디렉터리만 안전하게 조작할 수 있습니다.

1. 인증 (Git API 키)

• 포털 마이페이지에서 새 API 키 발급 (값 형식: tjgit_…, 발급 시 1회 표시, 활성 최대 5개).
• Git API 호출 시 키를 헤더 또는 JSON 본문에 포함합니다. 키 소유자 본인 저장소만 조작됩니다.
• 키 발급/목록/폐기는 포털 세션이 필요합니다. 액션: git_api_key_create, git_api_key_list, git_api_key_revoke.
• CORS: https://*.ctrlcv.kr에서 브라우저 호출 가능 (키는 프론트에 하드코딩하지 말고, 가능하면 서버 경유).
• 포털 세션이 있으면 키 없이도 호출 가능(폴백). 학생 사이트·스크립트는 키 사용을 권장합니다.

// 권장: Authorization 헤더
Authorization: Bearer tjgit_xxxxxxxx...

// 또는
X-Git-Api-Key: tjgit_xxxxxxxx...

// 또는 JSON body
{
  "git_action": "history",
  "api_key": "tjgit_xxxxxxxx..."
}

curl -s https://ctrlcv.kr/api.php?action=git_api \
  -H "Authorization: Bearer tjgit_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"git_action":"history"}'

3. 환경설정 (폴더 대상 / 예외)

commit은 설정에 맞는 파일만 repo.git에 커밋합니다. 기본값은 targets: ["*"] (public_html 전체, 강제 예외 제외)입니다.

강제 제외(항상): .env, .env.example, .git

// 설정 조회
{ "git_action": "get_settings" }

// 설정 저장
{
  "git_action": "save_settings",
  "targets": [".", "01", "api"],
  "excludes": ["node_modules", "*.log", "package-lock.json"]
}

// 저장 전 미리보기
{
  "git_action": "preview_targets",
  "targets": ["01"],
  "excludes": ["01/images"]
}

// get_settings 응답 일부
{
  "success": true,
  "settings": { "targets": ["*"], "excludes": [], "updated_at": "..." },
  "folders": [ { "path": "*", "label": "(전체 public_html)" }, ... ],
  "forced_excludes": [".env", ".env.example", ".git"],
  "preview_count": 42,
  "preview_files": ["index.php", "01/about.php", "..."],
  "storage": "repo.git"
}

2. 한국 시간(KST) 정책

서버 OS·PHP·Git 환경이 달라도, Git API는 항상 Asia/Seoul을 사용합니다.

UI에 시간을 표시할 때는 date(이미 KST)를 그대로 쓰면 됩니다. 절대 시각 재계산이 필요하면 date_raw를 파싱하세요.

4. 주요 API 동작 기능 (git_action)

요청 body는 JSON 객체입니다. git_action이 필수이며, 생략 시 기본값은 status입니다. 저장소가 없을 때 주요 동작 호출 시 repo.git이 자동 초기화됩니다.

{
  "git_action": "init"
}

{
  "git_action": "status"
}

// 응답 예시
{
  "success": true,
  "initialized": true,
  "short_output": " M index.html\n?? app.js",
  "output": "On branch master\n..."
}

{
  "git_action": "commit",
  "commit_msg": "메인 디자인 및 반응형 UI 작성 완료"
}

// 응답 예시
{
  "success": true,
  "message": "Git 커밋이 저장되었습니다. (12개 파일)",
  "output": "...",
  "file_count": 12,
  "files": ["index.php", "01/about.php"],
  "committed_at": "2026-07-29 14:30:00",
  "timezone": "Asia/Seoul",
  "storage": "repo.git"
}

{
  "git_action": "history"
}

// 응답 예시
{
  "success": true,
  "timezone": "Asia/Seoul",
  "commits": [
    {
      "hash": "a1b2c3d",
      "author": "test",
      "date": "2026-07-29 14:30:00",
      "date_raw": "2026-07-29T14:30:00+09:00",
      "message": "메인 디자인 및 반응형 UI 작성 완료"
    }
  ],
  "raw_output": "a1b2c3d|test|2026-07-29T14:30:00+09:00|메인 디자인..."
}

{
  "git_action": "rollback",
  "commit_hash": "a1b2c3d"
}

{
  "git_action": "diff"
}

// 특정 커밋 기준
{
  "git_action": "diff",
  "commit_hash": "a1b2c3d"
}

// Clone (HTTPS GitHub URL)
{
  "git_action": "clone",
  "repo_url": "https://github.com/username/repository"
}

// Pull
{
  "git_action": "pull"
}

5. 공통 응답 규칙

• 성공 시 대체로 "success": true
• 실패 시 "success": false 와 message
• 시간 관련 필드는 한국 시간 기준 (표시용 date / committed_at)
• 본문 인코딩: UTF-8 JSON

6. JavaScript fetch() 연동 예제

포털 로그인 후 학생 서브도메인 페이지에서도 동일하게 호출할 수 있습니다. (반드시 credentials: 'include')

const GIT_API = 'https://ctrlcv.kr/api.php?action=git_api';
// 포털에서 발급한 키 (서버 사이드에 두는 것을 권장)
const GIT_API_KEY = 'tjgit_YOUR_KEY';

async function gitApi(git_action, payload = {}) {
    const res = await fetch(GIT_API, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + GIT_API_KEY
        },
        body: JSON.stringify({ git_action, ...payload })
    });
    return res.json();
}

// 1) 커밋 타임라인 (KST date 사용)
async function loadGitHistory() {
    const data = await gitApi('history');
    if (!data.success) {
        console.error(data.message);
        return;
    }
    console.log('timezone:', data.timezone); // "Asia/Seoul"
    data.commits.forEach(c => {
        // c.date → "2026-07-29 14:30:00" (이미 한국 시간)
        console.log(`[${c.date}] ${c.hash} ${c.message}`);
    });
}

// 2) 버전 커밋
async function saveVersion(msg) {
    const data = await gitApi('commit', { commit_msg: msg });
    if (data.success) {
        console.log('저장 시각(KST):', data.committed_at);
    }
}

// 3) 과거 버전으로 복구
async function restoreVersion(hash) {
    const data = await gitApi('rollback', { commit_hash: hash });
    console.log(data.message);
}

// 4) 화면에 리스트 렌더링 예시
async function renderHistory(listEl) {
    const data = await gitApi('history');
    if (!data.success) {
        listEl.textContent = data.message || '조회 실패';
        return;
    }
    listEl.innerHTML = data.commits.map(c => `
      <li>
        <strong>${c.message}</strong>
        <span>${c.date}</span>
        <code>${c.hash}</code>
      </li>
    `).join('');
}

7. 오류 메시지

8. 주의사항

• 버전 기록은 공식 Git 저장소 /home/아이디/repo.git에 커밋으로 보관됩니다.
• 커밋 범위는 get_settings / save_settings로 조절합니다.
• rollback은 working tree를 덮어씁니다. 범위 내 변경이 있으면 자동 백업 커밋 후 복구합니다.
• 시간 표시는 date / committed_at (KST)을 사용하세요.
• 학생 사이트·스크립트는 Git API 키로 호출. 키를 공개 HTML/JS에 올리지 마세요.
• 키 유출 시 포털에서 즉시 폐기 후 재발급하세요.