GitHours
Sign InTry Free

Documentation

Everything you need to connect a repository, run an analysis, and share a report a client will trust.

Contents

Quick Start

1

Create Project

Start by creating a new project to organize your repository analysis.

2

Connect Repository

Enter a Git URL or upload a bundle file for offline repositories.

3

Run Analysis

Configure options like date range and gap threshold, then analyze.

4

View Results

Review time breakdown, export PDF reports, or share via link.

How Time Calculation Works

"How can software know how long I worked?"

The answer lies in a simple observation: commits are timestamps of your work. When you're actively coding, you commit frequently. When you take a break, there's a gap. GitHours reads this natural rhythm to reconstruct your work sessions.

2 hoursGap Threshold

The gap threshold is the maximum time between commits counted as continuous work. When commits are more than 2 hours apart, we treat them as separate work sessions.

This prevents overnight breaks, lunch, and meetings from counting as work time.

Adjust this in Project Settings if you commit less frequently.

30 minFirst Commit Time

The first commit in each session is assigned 30 minutes of work time. Why?

  • You likely worked before that first commit (setup, reading code)
  • Without this, the first commit would count as 0 minutes
  • 30 minutes is a conservative estimate for initial work

Depends on commit frequencyAccuracy Expectations

Closest

Regular commits (every 30-60 min)

Looser

Moderate commits (every 1-2 hours)

Loosest

Infrequent commits (every 3+ hours)

Pro tip: GitHours works best when you commit frequently. This is also a best practice for version control!

FAQAddressing Common Questions

"What if I work for 3 hours without committing?"

The gap threshold handles this. A 3-hour gap creates a new session, each getting +30 min start time. If you commit infrequently, increase your gap threshold to 3-4 hours in Project Settings.

"What if I make tons of tiny commits?"

Time is calculated from gaps between commits, not commit count. 10 commits in 1 hour = ~1 hour of work. 2 commits in 1 hour = ~1 hour of work.

"What about meetings, code review, thinking time?"

GitHours measures coding time—time actively working in the codebase. It's intentionally a conservative lower bound. Every measured interval comes from actual commit timestamps, plus a disclosed 30-minute credit at the start of each session—objective, checkable, and stated up front.

The Bottom Line

GitHours reconstructs your development time from commit timestamps, plus a disclosed 30-minute credit per session — with no timers to start and no time to enter by hand.

No timers to start/stopNo manual time entryRetroactive analysisVerifiable by clientsPublished, checkable methodology

Features

Repository Connections

Connect a repository by URL, or upload a bundle file.

  • Public and private repositories
  • Personal Access Token authentication
  • Bundle file upload for offline repos
  • GitHub, GitLab, Bitbucket support

Analysis Options

Customize how your time is calculated.

  • Configurable gap threshold
  • Date range filtering
  • Author filtering
  • Merge commit handling

Export & Sharing

Share results with clients and teams.

  • Professional PDF reports
  • Shareable public links
  • Methodology section in PDF reports

Frequently Asked Questions

Getting Started

How do I create my first project?

Click the "New Project" button in your dashboard or navigate to /projects/new. Enter a project name, connect your repository, and you're ready to run your first analysis.

What Git URLs are supported?

GitHours clones repositories over HTTPS from:

  • GitHub: https://github.com/user/repo.git
  • GitLab: https://gitlab.com/user/repo.git
  • Bitbucket: https://bitbucket.org/user/repo.git
  • Self-hosted: any Git server reachable on the public internet whose clone URL ends in .git

How do I upload a bundle file?

For repositories without network access, create a Git bundle:

git bundle create repo.bundle --all

Then upload the .bundle file when creating your project. GitHours will extract and analyze all commits.

How do I analyze a private repository?

There are two ways to analyze private repositories:

Option 1: Git Bundle (Recommended)

Create a bundle locally and upload it—no credentials stored on our servers:

git bundle create repo.bundle --all

Option 2: Personal Access Token

Include a token in the repository URL:

https://<token>@github.com/user/repo.git

GitHub: Settings → Developer settings → Personal access tokens → Generate with repo scope

GitLab: Settings → Access Tokens → Create with read_repository scope

Full OAuth integration (connect your GitHub/GitLab account) is coming soon.

Analysis & Results

What is the gap threshold?

The gap threshold (default: 2 hours) is the maximum time between commits that counts as continuous work.

If you commit at 9:00 AM and again at 10:30 AM (1.5 hour gap), that's counted as continuous work. But if your next commit is at 3:00 PM (4.5 hour gap), that starts a new session.

Adjust this in Project Settings if you commit less frequently.

How accurate is the time calculation?

Accuracy depends on your commit habits:

  • Regular commits (every 30-60 min): closest to actual working time
  • Moderate commits (every 1-2 hours): intervals include more unobserved time
  • Infrequent commits (every 3+ hours): long gaps are split into separate sessions, so unobserved work is not counted

For best results, commit frequently. This is also a Git best practice!

Why are some commits flagged as suspicious?

Commits are flagged when the time gap suggests potential inaccuracy—like a gap between 1-3x the threshold. This doesn't mean the data is wrong, just that you should review it. Long coding sessions without commits may be underestimated.

Reports & Sharing

How do I export a PDF report?

On any project's analysis page, click the "Export PDF" button. The report includes summary metrics, charts, methodology explanation, and a detailed commit table—perfect for sharing with clients or keeping records.

How do I create a shareable link?

Open the results for a project and click "Share" next to the export buttons. Anyone with the link can view the read-only report—no login required.

Links expire after 30 days by default. 8 hours, 1 day, 7 days, 90 days, and no expiry at all are also available. The same dialog lists every link for that timeline, so you can copy or revoke one at any time.

Troubleshooting

My repository URL isn't working

Common issues:

  • Private repo: Use a Personal Access Token in the URL or upload a bundle file (see "How do I analyze a private repository?" above)
  • Wrong URL format: Make sure the URL ends in .git
  • Token expired: Generate a new Personal Access Token and update the URL
  • Insufficient permissions: Ensure your token has repo scope (GitHub) or read_repository (GitLab)

The analysis is taking too long

Large repositories with thousands of commits may take a minute to analyze. If it's taking longer, try filtering by date range to analyze a smaller subset of commits.

Contact

Have a question about a report, or how GitHours calculates time? Reach out and we'll get back to you as soon as possible.

Contact Support
Try Free