Skip to content

Commit 5df9b68

Browse files
shinokadashinokada
committed
docs: README and docs/README update
1 parent b0741d8 commit 5df9b68

File tree

2 files changed

+285
-101
lines changed

2 files changed

+285
-101
lines changed

‎README.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
<p align="center">
2+
<img width="400" src="https://raw.githubusercontent.com/shinokada/gitstart/main/images/gitstart.png" />
3+
</p>
4+
5+
<p align="center">
6+
<a href='https://ko-fi.com/Z8Z2CHALG' target='_blank'><img height='42' style='border:0px;height:42px;' src='https://storage.ko-fi.com/cdn/kofi3.png?v=3' alt='Buy Me a Coffee at ko-fi.com' /></a>
7+
</p>
8+
9+
<h1 align="center">Gitstart</h1>
10+
11+
## Overview
12+
13+
> Gitstart creates, adds, and pushes with one line.
14+
15+
Gitstart automates creating a GitHub repository. It will:
16+
17+
- Create `.gitignore` if you provide a language
18+
- Create a license file based on your choice
19+
- Create a new repository at GitHub.com (public or private)
20+
- Create a `README.md` file with the repository name
21+
- Initialize a git repository (if needed)
22+
- Add files and commit with a custom message
23+
- Add the remote and push
24+
- Support existing directories and projects
25+
26+
## Requirements
27+
28+
- [GitHub CLI](https://cli.github.com/manual/) (`gh`), authenticated
29+
- `git` installed
30+
- macOS, Linux, or Windows
31+
32+
## Installation
33+
34+
### Homebrew (macOS/Linux)
35+
36+
```sh
37+
brew install shinokada/gitstart/gitstart
38+
```
39+
40+
### Windows Scoop
41+
42+
```sh
43+
scoop bucket add shinokada https://github.com/shinokada/scoop-bucket
44+
scoop install gitstart
45+
```
46+
47+
### Debian/Ubuntu
48+
49+
Download the latest `.deb` from the [releases page](https://github.com/shinokada/gitstart/releases) and run:
50+
51+
```sh
52+
sudo apt install ./gitstart_x.x.x_linux_amd64.deb
53+
```
54+
55+
### Fedora/RHEL
56+
57+
Download the latest `.rpm` from the [releases page](https://github.com/shinokada/gitstart/releases) and run:
58+
59+
```sh
60+
sudo rpm -i gitstart_x.x.x_linux_amd64.rpm
61+
```
62+
63+
### Go install
64+
65+
```sh
66+
go install github.com/shinichiokada/gitstart@latest
67+
```
68+
69+
This places the `gitstart` binary in your `$GOPATH/bin` or `$GOBIN` directory. Make sure that directory is in your `PATH`.
70+
71+
## Usage
72+
73+
### Basic Usage
74+
75+
```sh
76+
# Login to GitHub
77+
gh auth login
78+
79+
# Create a new repository
80+
gitstart -d repo-name
81+
82+
# Create in current directory
83+
cd existing_project
84+
gitstart -d .
85+
```
86+
87+
### Options
88+
89+
```
90+
-d, --directory DIRECTORY Directory name or path (use . for current directory)
91+
-l, --language LANGUAGE Programming language for .gitignore
92+
-p, --private Create a private repository (default: public)
93+
-P, --public Create a public repository
94+
-b, --branch BRANCH Branch name (default: main)
95+
-m, --message MESSAGE Initial commit message (default: "Initial commit")
96+
--description DESC Repository description
97+
-n, --dry-run Show what would happen without executing
98+
-q, --quiet Minimal output
99+
-h, --help Show help message
100+
version Show version
101+
```
102+
103+
### Examples
104+
105+
**Create a new repository:**
106+
```sh
107+
gitstart -d my-project
108+
```
109+
110+
**Create with specific programming language:**
111+
```sh
112+
gitstart -d my-python-app -l python
113+
```
114+
115+
**Create a private repository:**
116+
```sh
117+
gitstart -d secret-project -p
118+
```
119+
120+
**Use custom commit message and branch:**
121+
```sh
122+
gitstart -d my-app -m "First release" -b develop
123+
```
124+
125+
**Add repository description:**
126+
```sh
127+
gitstart -d awesome-tool --description "An amazing CLI tool for developers"
128+
```
129+
130+
**Preview changes without executing (dry run):**
131+
```sh
132+
gitstart -d test-repo --dry-run
133+
```
134+
135+
**Quiet mode for scripts:**
136+
```sh
137+
gitstart -d automated-repo -q
138+
```
139+
140+
**Initialize existing project:**
141+
```sh
142+
cd my-existing-project
143+
gitstart -d . -l javascript --description "My existing JavaScript project"
144+
```
145+
146+
**Show version:**
147+
```sh
148+
gitstart version
149+
```
150+
151+
### Working with Existing Directories
152+
153+
**Empty directory:** Creates repository normally
154+
155+
**Directory with files but no git:**
156+
- Warns about existing files
157+
- Asks for confirmation
158+
- Preserves existing files
159+
- Adds them to the initial commit
160+
161+
**Directory with existing git repository:**
162+
- Detects existing `.git` folder
163+
- Adds remote to existing repository
164+
- Preserves git history
165+
166+
**Existing LICENSE, README.md, or .gitignore:**
167+
- Detects existing files
168+
- Offers to append or skip
169+
- Prevents accidental overwrites
170+
171+
### Interactive License Selection
172+
173+
When you run gitstart, you'll be prompted to select a license:
174+
175+
```
176+
Select a license:
177+
1) MIT: I want it simple and permissive.
178+
2) Apache License 2.0: I need to work in a community.
179+
3) GNU GPLv3: I care about sharing improvements.
180+
4) None
181+
5) Quit
182+
```
183+
184+
## Error Handling
185+
186+
- **Automatic cleanup**: If repository creation fails, the remote repository is automatically deleted
187+
- **Validation checks**: Ensures all required tools are installed
188+
- **Auth verification**: Confirms you're logged in to GitHub
189+
- **File conflict detection**: Warns about existing files before overwriting
190+
- **Detailed error messages**: Clear information about what went wrong and how to fix it
191+
192+
## About Licensing
193+
194+
Read more about [Licensing](https://docs.github.com/en/free-pro-team@latest/rest/reference/licenses).
195+
196+
## Changelog
197+
198+
### Version 1.0.0 (2026)
199+
200+
Gitstart is now rewritten in Go with full cross-platform support (macOS, Linux, Windows).
201+
202+
### Version 0.4.0 (2026-01-18)
203+
204+
**New Features:**
205+
- Private repository support with `-p/--private` flag
206+
- Custom commit messages with `-m/--message` flag
207+
- Custom branch names with `-b/--branch` flag
208+
- Repository description with `--description` flag
209+
- Dry run mode with `--dry-run` flag
210+
- Quiet mode with `-q/--quiet` flag
211+
- Full support for existing directories and files
212+
- Automatic rollback on errors
213+
- Detection and handling of existing git repositories
214+
215+
**Improvements:**
216+
- XDG-compliant config directory (`~/.config/gitstart/config`)
217+
- Better error messages with context
218+
- File conflict detection and user prompts
219+
- Smarter handling of existing LICENSE, README, and .gitignore files
220+
221+
**Bug Fixes:**
222+
- Fixed issue with `gh repo create --clone` in existing directories
223+
- Proper handling of existing files to prevent data loss
224+
225+
### Version 0.3.0
226+
- Initial public release
227+
228+
## Author
229+
230+
Shinichi Okada
231+
232+
- [Medium](https://shinichiokada.medium.com/)
233+
- [Twitter](https://twitter.com/shinokada)
234+
235+
## License
236+
237+
Copyright (c) 2021-2026 Shinichi Okada (@shinokada)
238+
This software is released under the MIT License, see LICENSE.

0 commit comments

Comments
 (0)