git-templates/gitea_setup.md

# Complete Gitea Setup Guide for Beginners

## A) Initial Setup of Gitea on Computer

### 1. Install Git on Your Computer

**Windows:**
- Download Git from https://git-scm.com/download/win
- Run installer with default settings
- Open Git Bash or Command Prompt

**macOS:**
- Install via Homebrew: `brew install git`
- Or download from https://git-scm.com/download/mac

**Linux (Ubuntu/Debian):**
- Install via package manager: `sudo apt-get install git`

### 2. Verify Git Installation
```bash
git --version
```

### 3. Connect Computer to Your Existing Codebase/Folder

**Option 1: Connect Existing Local Folder to Gitea**
```bash
cd /path/to/your/existing/project
git init
git remote add origin git@your-gitea-server:username/repository-name.git
git add .
git commit -m "Initial commit"
git push -u origin main
```

**Option 2: Clone Existing Repository from Gitea**
```bash
git clone git@your-gitea-server:username/repository-name.git
cd repository-name
```

## B) Initial Configuration on New Computer

### 1. Configure Git Identity
```bash
git config --global user.name "Your Full Name"
git config --global user.email "your.email@example.com"
git config --global core.editor "nano"  # or "code" for VS Code
git config --global color.ui true
```

### 2. Generate SSH Key for Secure Authentication
```bash
# Generate new SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"

# Start SSH agent
eval "$(ssh-agent -s)"

# Add key to agent
ssh-add ~/.ssh/id_ed25519

# Display public key to copy to Gitea
cat ~/.ssh/id_ed25519.pub
```

### 3. Add SSH Key to Gitea Account
1. Copy the public key output from above
2. Log into Gitea web interface
3. Go to Settings > SSH/GPG Keys
4. Click "Add Key"
5. Paste public key in Content field
6. Click "Add Key"

### 4. Test SSH Connection
```bash
ssh -T git@your-gitea-server.com
```
You should see a success message.

### 5. Set Up Git Aliases (Optional but Helpful)
```bash
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --decorate"
```

## C) Steps to Form a New Project Each Time

### 1. Create Repository in Gitea Web Interface
1. Log into Gitea
2. Click "+" menu in top-right corner
3. Select "New Repository"
4. Fill out repository details:
   - **Repository Name:** use-lowercase-with-hyphens
   - **Description:** Brief project description
   - **Visibility:** Public or Private
   - **Initialize Repository:** Check if starting fresh
   - **Add .gitignore:** Select template for your language
   - **Add License:** Choose appropriate license
5. Click "Create Repository"

### 2. Clone and Set Up Locally
```bash
# Clone the new repository
git clone git@your-gitea-server:username/repository-name.git

# Navigate to project directory
cd repository-name

# Create basic project structure
mkdir src docs tests
touch src/main.py  # or main.js, main.cpp, etc.

# Add initial files
git add .
git commit -m "Initial project structure"
git push origin main
```

### 3. Create Development Branch
```bash
# Create and switch to development branch
git checkout -b develop

# Push development branch to remote
git push -u origin develop
```

## D) Templates and Documents for New Setup

### 1. Essential Files Every Repository Should Have

#### README.md Template
```markdown
# Project Name

Brief description of what this project does.

## Features
- Feature 1
- Feature 2
- Feature 3

## Installation
```bash
git clone git@your-gitea-server:username/project-name.git
cd project-name
# Add installation steps
```

## Usage
```bash
# Add usage examples
```

## Configuration
Describe any configuration needed.

## Contributing
Guidelines for contributing to the project.

## License
This project is licensed under the [License Name](LICENSE) - see the LICENSE file for details.
```

#### .gitignore Template (General)
```
# Operating System Files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# Editor Files
.vscode/
.idea/
*.swp
*.swo
*~

# Log Files
*.log
logs/

# Environment Files
.env
.env.local
.env.production
*.secret

# Temporary Files
*.tmp
*.temp
temp/
tmp/

# Build Files
dist/
build/
*.o
*.exe
```

#### LICENSE Template (MIT)
```
MIT License

Copyright (c) [year] [fullname]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

#### CHANGELOG.md Template
```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features

### Changed
- Changes in existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Security improvements

## [1.0.0] - 2024-01-01
### Added
- Initial release
```

### 2. Gitea-Specific Templates

#### Issue Template (.gitea/ISSUE_TEMPLATE.md)
```markdown
## Bug Description
A clear and concise description of what the bug is.

## Steps to Reproduce
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

## Expected Behavior
A clear and concise description of what you expected to happen.

## Screenshots
If applicable, add screenshots to help explain your problem.

## Environment
- OS: [e.g. Windows 10, macOS 12, Ubuntu 20.04]
- Version: [e.g. 1.2.3]
- Browser: [e.g. Chrome 96, Firefox 95]

## Additional Context
Add any other context about the problem here.
```

#### Pull Request Template (.gitea/PULL_REQUEST_TEMPLATE.md)
```markdown
## Description
Brief description of changes made.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Testing
- [ ] I have tested this change locally
- [ ] I have added/updated tests as needed
- [ ] All existing tests pass

## Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
```

## E) Very Detailed Daily Coding Workflow

### 1. Start of Each Work Session
```bash
# Check current status
git status

# Get latest changes from remote
git pull origin main

# Create new feature branch (use descriptive names)
git checkout -b feature/add-user-authentication
# or
git checkout -b bugfix/fix-login-error
# or  
git checkout -b docs/update-readme
```

### 2. During Development

#### Making Changes
```bash
# Check what files have changed
git status

# See specific changes in files
git diff

# See changes for specific file
git diff filename.py
```

#### Staging and Committing Changes
```bash
# Stage specific files
git add src/auth.py src/login.py

# Or stage all changes
git add .

# Or stage all changes in current directory
git add -A

# Check what's staged
git status

# Commit with descriptive message
git commit -m "Add user authentication with email verification"

# Or commit with detailed message
git commit -m "Add user authentication system

- Implement email-based user registration
- Add password hashing with bcrypt
- Create login/logout functionality
- Add session management
- Include email verification workflow

Fixes #123"
```

#### Best Practices for Commit Messages
- Use present tense imperative mood ("Add feature" not "Added feature")
- Keep first line under 50 characters
- Add blank line before detailed description
- Reference issue numbers when applicable
- Use conventional commit format:
  - `feat:` for new features
  - `fix:` for bug fixes
  - `docs:` for documentation
  - `style:` for formatting changes
  - `refactor:` for code refactoring
  - `test:` for adding tests

#### Pushing Changes
```bash
# Push current branch to remote
git push origin feature/add-user-authentication

# If first time pushing this branch
git push -u origin feature/add-user-authentication
```

### 3. Checking Progress and History
```bash
# View commit history
git log --oneline

# View detailed history
git log --graph --decorate --oneline

# View changes between commits
git log -p

# View specific file history
git log --follow filename.py

# View who changed what in a file
git blame filename.py
```

### 4. Handling Merge Conflicts
```bash
# If pull/merge results in conflicts
git status  # Shows conflicted files

# Edit conflicted files manually, looking for:
# <<<<<<< HEAD
# Your changes
# =======
# Their changes
# >>>>>>> branch-name

# After resolving conflicts
git add conflicted-file.py
git commit -m "Resolve merge conflict in user authentication"
```

### 5. End of Feature Development
```bash
# Switch back to main branch
git checkout main

# Get latest changes
git pull origin main

# Merge feature branch
git merge feature/add-user-authentication

# Push merged changes
git push origin main

# Delete feature branch locally
git branch -d feature/add-user-authentication

# Delete feature branch on remote
git push origin --delete feature/add-user-authentication
```

### 6. Daily Maintenance Commands
```bash
# See all branches (local and remote)
git branch -a

# See remote repositories
git remote -v

# Clean up remote tracking branches
git remote prune origin

# See repository status
git status

# See what's different from last commit
git diff HEAD~1

# Undo last commit (but keep changes)
git reset --soft HEAD~1

# Undo changes to a file
git checkout -- filename.py

# Create and apply patches
git format-patch -1 HEAD
git apply patch-file.patch
```

### 7. Working with Multiple Remotes
```bash
# Add additional remote (e.g., for backup)
git remote add backup git@backup-server:username/repository.git

# Push to specific remote
git push backup main

# Pull from specific remote
git pull backup main
```

### 8. Stashing Work in Progress
```bash
# Save current work without committing
git stash push -m "Work in progress on authentication"

# List stashes
git stash list

# Apply most recent stash
git stash pop

# Apply specific stash
git stash apply stash@{1}

# Drop a stash
git stash drop stash@{1}
```

### 9. Emergency Procedures

#### Undo Last Commit
```bash
# Undo last commit but keep changes
git reset --soft HEAD~1

# Undo last commit and lose changes
git reset --hard HEAD~1
```

#### Recovery
```bash
# Find lost commits
git reflog

# Recover specific commit
git checkout commit-hash

# Create branch from recovered commit
git checkout -b recovery-branch
```

This comprehensive guide provides everything needed to effectively use Git with Gitea for personal coding projects.