|
1 | | -## TODO: |
2 | | - |
3 | | -### Dev |
4 | | - |
5 | | -- [x] Error handling for malformed files |
6 | | -- [x] [Toaster](https://www.npmjs.com/package/react-toastify) |
7 | | -- [x] Create a loader to give feedback from the time the user has clicked the upload button to the time the state has actually changed |
8 | | -- [x] Update the linter to be more strict |
9 | | -- [x] Do not allow relative imports (use only absolute imports with [vite-tsconfig-paths](https://www.npmjs.com/package/vite-tsconfig-paths)) |
10 | | -- [x] Add prettier (and generate config) |
11 | | -- [x] Add cspell spell checker |
12 | | -- [x] Add husky pre-commit hooks |
13 | | -- [x] Code chunking for improved performance |
14 | | -- [x] Use checkboxes in the directory tree to indicate which files are shown in the main section |
15 | | -- [ ] Construct more resilient unit tests |
16 | | -- [ ] i18n translations |
17 | | -- [ ] Light/Dark mode |
18 | | -- [ ] Make use of the `getTreeStatistics` function |
19 | | - |
20 | | -### Product |
21 | | - |
22 | | -- [ ] ~~Make the size of the sidebar adjustable (by dragging it?)~~ |
23 | | -- [x] Add support for mobile by making the sidebar take up the full width of the screen and reducing the font size |
24 | | -- [ ] Make the file names sticky as the user scrolls down when examining the diffs |
25 | | -- [ ] Update the `FileChangeType` status next to the file names to have their own colours |
| 1 | +# Diff Viewer |
| 2 | + |
| 3 | +A responsive web application for visualizing Git diff/patch files with an intuitive interface and multiple viewing modes. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +### Core Functionality |
| 8 | +- **File Upload**: Upload `.diff`, `.patch`, or `.txt` files containing Git diffs |
| 9 | +- **Dual View Modes**: Switch between unified and split-view diff displays |
| 10 | +- **Directory Tree**: Navigate through changed files using an organized sidebar tree structure |
| 11 | +- **File Statistics**: View comprehensive statistics including additions, deletions, and change types |
| 12 | +- **Error Handling**: Robust error handling for malformed or corrupted diff files |
| 13 | + |
| 14 | +### View Modes |
| 15 | +- **Unified View**: Traditional single-column diff display with line-by-line changes |
| 16 | +- **Split View**: Side-by-side comparison showing old and new versions |
| 17 | +- **Word-level Highlighting**: Precise highlighting of changes within modified lines |
| 18 | +- **Line Numbers**: Accurate line numbering for both old and new file versions |
| 19 | + |
| 20 | +### User Experience |
| 21 | +- **Responsive Design**: Works seamlessly across desktop and mobile devices |
| 22 | +- **Loading States**: Visual feedback during file processing |
| 23 | +- **Toast Notifications**: User-friendly success and error messages |
| 24 | +- **Collapsible Sidebar**: Adjustable interface for optimal viewing |
| 25 | + |
| 26 | +### File Change Support |
| 27 | +- **Added files**: New files in the repository |
| 28 | +- **Modified files**: Changes to existing files |
| 29 | +- **Deleted files**: Removed files (excluded from tree view) |
| 30 | +- **Renamed files**: Files that have been moved or renamed |
| 31 | + |
| 32 | +## Getting Started |
| 33 | + |
| 34 | +### Prerequisites |
| 35 | +- Node.js (v18 or higher) |
| 36 | +- pnpm (recommended) or npm/yarn |
| 37 | + |
| 38 | +### Installation |
| 39 | + |
| 40 | +1. **Clone the repository** |
| 41 | + ```bash |
| 42 | + git clone https://github.com/barrymun/diff-viewer.git |
| 43 | + cd diff-viewer |
| 44 | + ``` |
| 45 | + |
| 46 | +2. **Install dependencies** |
| 47 | + ```bash |
| 48 | + pnpm install |
| 49 | + # or alternatively: npm install / yarn install |
| 50 | + ``` |
| 51 | + |
| 52 | +3. **Start the development server** |
| 53 | + ```bash |
| 54 | + pnpm dev |
| 55 | + # or alternatively: npm run dev / yarn dev |
| 56 | + ``` |
| 57 | + |
| 58 | +4. **Open your browser** |
| 59 | + Navigate to `http://localhost:5173` to view the application. |
| 60 | + |
| 61 | +## Usage |
| 62 | + |
| 63 | +### Basic Usage |
| 64 | +1. **Upload a diff file**: Click the "Upload files" button and select a `.diff`, `.patch`, or `.txt` file |
| 65 | +2. **Browse files**: Use the sidebar directory tree to navigate through changed files |
| 66 | +3. **Switch views**: Toggle between "Unified" and "Split" view modes using the view toggle buttons |
| 67 | +4. **Examine changes**: Review detailed line-by-line changes with syntax highlighting |
| 68 | + |
| 69 | +### Supported File Formats |
| 70 | +- **Git diff output**: Standard `git diff` command output |
| 71 | +- **Git format-patch**: Output from `git format-patch` |
| 72 | +- **Unix diff**: Traditional Unix diff format |
| 73 | +- **Custom patches**: Any text file following standard diff format |
| 74 | + |
| 75 | +### Generating Compatible Diff Files |
| 76 | + |
| 77 | +#### From Git repositories: |
| 78 | +```bash |
| 79 | +# Generate diff for uncommitted changes |
| 80 | +git diff > changes.diff |
| 81 | + |
| 82 | +# Generate diff between commits |
| 83 | +git diff commit1..commit2 > changes.diff |
| 84 | + |
| 85 | +# Generate formatted patches |
| 86 | +git format-patch -1 HEAD --output-directory=patches/ |
| 87 | +``` |
| 88 | + |
| 89 | +#### From command line: |
| 90 | +```bash |
| 91 | +# Compare two files |
| 92 | +diff -u file1.txt file2.txt > changes.diff |
| 93 | + |
| 94 | +# Compare directories |
| 95 | +diff -ur directory1/ directory2/ > changes.diff |
| 96 | +``` |
| 97 | + |
| 98 | +## Project Structure |
| 99 | + |
| 100 | +``` |
| 101 | +src/ |
| 102 | +├── components/ # Reusable UI components |
| 103 | +│ ├── app/ # Main application component |
| 104 | +│ ├── loader/ # Loading indicator |
| 105 | +│ └── styled/ # Styled Material-UI components |
| 106 | +├── contexts/ # React contexts for state management |
| 107 | +├── features/ # Feature-specific components |
| 108 | +│ ├── diffViewer/ # Core diff viewing functionality |
| 109 | +│ │ ├── components/ # Upload, view toggle, patch info |
| 110 | +│ │ ├── splitViewer/# Split view implementation |
| 111 | +│ │ └── unifiedViewer/ # Unified view implementation |
| 112 | +│ └── directoryTree/ # File tree navigation |
| 113 | +├── hooks/ # Custom React hooks |
| 114 | +├── utils/ # Utility functions and types |
| 115 | +└── zustand/ # Global state management |
| 116 | +``` |
| 117 | + |
| 118 | +## Development |
| 119 | + |
| 120 | +### Available Scripts |
| 121 | + |
| 122 | +```bash |
| 123 | +# Development |
| 124 | +pnpm dev # Start development server |
| 125 | +pnpm build # Build for production |
| 126 | +pnpm preview # Preview production build |
| 127 | + |
| 128 | +# Code Quality |
| 129 | +pnpm lint # Run ESLint |
| 130 | +pnpm lint-fix # Fix ESLint issues automatically |
| 131 | +pnpm test # Run test suite |
| 132 | +pnpm cspell # Run spell checker |
| 133 | + |
| 134 | +# Git Hooks |
| 135 | +pnpm prepare # Setup Husky pre-commit hooks |
| 136 | +``` |
| 137 | + |
| 138 | +### Technology Stack |
| 139 | + |
| 140 | +**Frontend Framework** |
| 141 | +- React 19.1.0 with TypeScript |
| 142 | +- Vite for build tooling and development |
| 143 | + |
| 144 | +**UI Library** |
| 145 | +- Material-UI (MUI) v7 for components and theming |
| 146 | +- Material Icons for iconography |
| 147 | +- Custom styled components |
| 148 | + |
| 149 | +**State Management** |
| 150 | +- Zustand for global state |
| 151 | +- React Context for feature-specific state |
| 152 | + |
| 153 | +**Diff Processing** |
| 154 | +- `diff` library for parsing patch files |
| 155 | +- Custom algorithms for line alignment and word-level diffing |
| 156 | + |
| 157 | +**Code Quality** |
| 158 | +- ESLint with strict TypeScript rules |
| 159 | +- Prettier for code formatting |
| 160 | +- Husky for pre-commit hooks |
| 161 | +- CSpell for spell checking |
| 162 | +- Vitest for unit testing |
| 163 | + |
| 164 | +### Code Standards |
| 165 | + |
| 166 | +The project enforces strict code quality standards: |
| 167 | +- **No relative imports**: All imports use absolute paths with `@/` prefix |
| 168 | +- **Strict TypeScript**: Comprehensive type checking enabled |
| 169 | +- **Consistent formatting**: Prettier configuration for uniform code style |
| 170 | +- **File naming**: camelCase naming convention enforced |
| 171 | +- **Import organization**: Automatic import sorting and grouping |
| 172 | + |
| 173 | +## Testing |
| 174 | + |
| 175 | +Run the test suite: |
| 176 | +```bash |
| 177 | +pnpm test |
| 178 | +``` |
| 179 | + |
| 180 | +The project includes unit tests for core functionality: |
| 181 | +- Diff parsing and processing |
| 182 | +- Line alignment algorithms |
| 183 | +- Component rendering logic |
| 184 | + |
| 185 | +## Roadmap |
| 186 | + |
| 187 | +### Completed Features |
| 188 | +- Error handling for malformed files |
| 189 | +- Toast notifications and user feedback |
| 190 | +- Loading states and progress indicators |
| 191 | +- Strict linting and code quality tools |
| 192 | +- Absolute import paths with TypeScript |
| 193 | +- Code formatting with Prettier |
| 194 | +- Spell checking integration |
| 195 | +- Pre-commit hooks with Husky |
| 196 | +- Performance optimization with code chunking |
| 197 | + |
| 198 | +### Planned Features |
| 199 | +See [TODO.md](TODO.md) |
| 200 | + |
| 201 | +## Contributing |
| 202 | + |
| 203 | +1. **Fork the repository** |
| 204 | +2. **Create a feature branch**: `git checkout -b feature/new-feature` |
| 205 | +3. **Make your changes** following the established code standards |
| 206 | +4. **Run tests**: `pnpm test` |
| 207 | +5. **Run linting**: `pnpm lint` |
| 208 | +6. **Commit your changes**: `git commit -m 'Add new feature'` |
| 209 | +7. **Push to branch**: `git push origin feature/new-feature` |
| 210 | +8. **Open a Pull Request** |
| 211 | + |
| 212 | +### Development Guidelines |
| 213 | +- Follow TypeScript strict mode requirements |
| 214 | +- Use absolute imports with `@/` prefix |
| 215 | +- Write unit tests for new features |
| 216 | +- Ensure all linting passes before committing |
| 217 | +- Use conventional commit messages |
| 218 | + |
| 219 | +## License |
| 220 | + |
| 221 | +This project is available under the MIT License. See the [LICENSE](LICENSE) file for more details. |
| 222 | + |
| 223 | +## Issues and Support |
| 224 | + |
| 225 | +If you encounter any issues or have questions: |
| 226 | +1. Check existing issues in the repository |
| 227 | +2. Create a new issue with detailed reproduction steps |
| 228 | +3. Include browser version and any error messages |
| 229 | + |
| 230 | +## Performance Considerations |
| 231 | + |
| 232 | +- **File Size**: The application handles large diff files efficiently, but very large files (>10MB) may impact performance |
| 233 | +- **Format**: Ensure your diff files follow standard Git diff format for optimal parsing |
| 234 | +- **Browser**: Modern browsers (Chrome 90+, Firefox 88+, Safari 14+) provide the best experience |
| 235 | +- **Screen Size**: Split view works best on larger screens; unified view is optimized for mobile devices |
0 commit comments