13 |
14 | {definition.name}
15 |
16 | {visible && (
17 |
18 | {definition.description}
19 |
22 |
23 | )}
24 |
25 | )
26 | }
27 |
--------------------------------------------------------------------------------
/src/components/Article.tsx:
--------------------------------------------------------------------------------
1 | import { useParams } from 'react-router-dom'
2 | import { useEffect, useState } from 'react'
3 | import Markdown from 'markdown-to-jsx'
4 | import { articlesList } from '../articles-list'
5 | import './Article.css'
6 |
7 | export default function Article() {
8 | const { article } = useParams<{ article: string }>()
9 | const [articleText, setArticleText] = useState('')
10 | const [articleExists, setArticleExists] = useState
24 | {articleExists ? {articleText} :
26 | )
27 | }
28 |
--------------------------------------------------------------------------------
/.devcontainer/base.Dockerfile:
--------------------------------------------------------------------------------
1 | # [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 18, 16, 14, 18-bullseye, 16-bullseye, 14-bullseye, 18-buster, 16-buster, 14-buster
2 | ARG VARIANT=16-bullseye
3 | FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}
4 |
5 | # Install tslint, typescript. eslint is installed by javascript image
6 | ARG NODE_MODULES="tslint-to-eslint-config typescript"
7 | COPY library-scripts/meta.env /usr/local/etc/vscode-dev-containers
8 | RUN su node -c "umask 0002 && npm install -g ${NODE_MODULES}" \
9 | && npm cache clean --force > /dev/null 2>&1
10 |
11 | # [Optional] Uncomment this section to install additional OS packages.
12 | # RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
13 | # && apt-get -y install --no-install-recommends This article doesn't exist
} 25 |
2 | 
3 |
A web application that makes it easy to find what a git command does by just typing it into the search bar.
6 | 7 |8 | Features • 9 | Upcoming Features • 10 | Supported Commands • 11 | Contribute 12 |
13 | 14 | ## Introduction 15 | 16 | This project is written with Typescript using React. It works only with a front-end, using parsing of command-line arguments and a simple .json file containing all the descriptions of the commands and their flags. It is also easy to self-host since it doesn't contain a server. 17 | 18 | ## Features 19 | 20 | What The Git only contains really basic git commands and flags so far, but the list will grow with time. I expect to support at least git add, git commit and git push. Feel free to contribute to fix issues that you found in the app or to add more git commands to it ! As this is a personal project, I would really appreciate it. 21 | 22 | It also features a system that embeds descriptions of git jargon such as staging area, commit etc. as hyperlinks in the command description. You can either hover them to see a short description, or click the "read article" button to be redirected on the full article. 23 | 24 | ## Upcoming features 25 | 26 | - More verbose errors (telling you where the command went wrong and why instead of just showing a generic error message) 27 | 28 | Feel free to submit an issue if you have feature requests, I'll gladly take them. 29 | 30 | ## Supported commands 31 | 32 | So far, only a few commands are supported, with a few flags: 33 | 34 | - git 35 | - add 36 | - commit 37 | - push 38 | - rebase 39 | - diff 40 | - log 41 | - pull 42 | - status 43 | 44 | ## Contribute 45 | 46 | As I stated above, pull requests, bug reports and feature requests are very much appreciated. This is a big project for me, and any help would be truly appreciated! I setup a couple of templates in the issues section if you want to contribute. I don't feel like adding a code of conduct, I only expect contributors to be respectful to each other. 47 | 48 | It is advised to read the [developer manual](DEVELOPMENT.md) before intending to contribute on the code. It's here to help you understand the structure of the project! 49 | 50 | ## Development 51 | 52 | ### Disclaimer 53 | 54 | This project now uses yarn, which is an alternative package manager for NodeJS. You can find it at https://yarnpkg.com/ if you don't already have it installed on your system. 55 | 56 | ### Run the app on a local machine 57 | 58 | In the project directory, you can run: 59 | 60 | ### `yarn` 61 | 62 | Runs yarn and downloads the related packages, and it's dependencies for this project 63 | 64 | ### `yarn run start` 65 | 66 | Runs the app in the development mode.\ 67 | Open [http://localhost:3000](http://localhost:3000) to view it in the browser. 68 | 69 | The page will reload if you make edits.\ 70 | You will also see any lint errors in the console. 71 | 72 | ### `yarn run build` 73 | 74 | Builds the app for production to the `build` folder.\ 75 | It correctly bundles React in production mode and optimizes the build for the best performance. 76 | 77 | The build is minified, and the filenames include the hashes.\ 78 | Your app is ready to be deployed! 79 | -------------------------------------------------------------------------------- /src/App.tsx: -------------------------------------------------------------------------------- 1 | import parser from 'yargs-parser' 2 | import { useState } from 'react' 3 | import './App.css' 4 | import { gitCommands, specialTokens } from './git-commands' 5 | import { 6 | getAvailableFlagsAsArray, 7 | getMatchingFlags, 8 | getParsedFlagsDescriptions, 9 | getAliasesAsObject, 10 | replaceSpecialTokens, 11 | parseDescription, 12 | } from './git-command-parsing' 13 | import { GitCommand, InputFlag } from './types' 14 | import { definitions } from './git-definitions' 15 | 16 | // Gets the matching git command from the git-commands.js file, and formats the description using the arguments if needed. 17 | function getGitCommand(inputCommand: string): GitCommand | null { 18 | // Get the command name and check if it exists 19 | const inputCommandName = inputCommand.split(' ')[1] 20 | const matchingCommand = gitCommands.commands.find((command) => command.name === inputCommandName) 21 | if (!(inputCommand.split(' ')[0] === 'git') || !matchingCommand) { 22 | return null 23 | } 24 | 25 | // Get all the available flags 26 | const availableFlags = gitCommands.commands.find((command) => command.name === inputCommandName) 27 | ?.flags 28 | 29 | // These arrays exist so they can be used with yargs-parser 30 | let availableFlagsAsArrays 31 | let aliasesObject 32 | 33 | if (availableFlags) { 34 | availableFlagsAsArrays = getAvailableFlagsAsArray(availableFlags) 35 | aliasesObject = getAliasesAsObject(availableFlags) 36 | } 37 | 38 | // Parse the arguments 39 | const parsedArgs = parser(inputCommand, { 40 | boolean: availableFlagsAsArrays?.booleanFlagsArray, 41 | string: availableFlagsAsArrays?.stringFlagsArray, 42 | alias: aliasesObject, 43 | }) 44 | 45 | // Restructure the arguments to be easier to work with 46 | // Instead of the flags being as keys value pairs in the object, put them in their own property called flags with a name and a value 47 | const parsedArguments = Object.entries(parsedArgs).reduce( 48 | (acc, [argumentKey, argumentValue]) => { 49 | if (argumentKey === '_') { 50 | return { ...acc, _: argumentValue } 51 | } 52 | if (argumentValue) { 53 | acc.flags.push({ name: argumentKey, value: argumentValue }) 54 | } 55 | return acc 56 | }, 57 | { _: [] as string[], flags: [] as InputFlag[] } 58 | ) 59 | 60 | let matchingFlags 61 | if (availableFlags) { 62 | matchingFlags = getMatchingFlags(availableFlags, parsedArguments) 63 | } 64 | 65 | // Check if the arguments contain special tokens and replace them by the description to be displayed in the description 66 | const updatedParsedArguments = replaceSpecialTokens(parsedArguments, specialTokens) 67 | 68 | // Replace string tokens with arguments and add a list of flags descriptions if needed 69 | const updatedMatchingCommand = { 70 | ...matchingCommand, 71 | description: parseDescription( 72 | matchingCommand as GitCommand, 73 | definitions, 74 | updatedParsedArguments 75 | ), 76 | flagsDescriptions: getParsedFlagsDescriptions(matchingFlags || [], updatedParsedArguments), 77 | } 78 | 79 | return updatedMatchingCommand 80 | } 81 | 82 | function renderCommandDescription(command: GitCommand) { 83 | let flagsDescriptions 84 | if (command.flagsDescriptions.length > 0) { 85 | flagsDescriptions = command.flagsDescriptions.map((flag) => { 86 | return ( 87 |
88 |
94 | )
95 | })
96 | }
97 |
98 | return (
99 | 89 | --{flag.name} 90 | {flag.aliases ? ` (${flag.aliases.map((alias) => `-${alias}`).join(' / ')})` : ''} 91 |
92 |{flag.description}
93 |
100 |
105 | )
106 | }
107 |
108 | function App() {
109 | const [matchingCommand, setMatchingCommand] = useState({} as GitCommand)
110 | const [inputCommand, setInputCommand] = useState('')
111 | const [isInvalid, setIsInvalid] = useState(false)
112 |
113 | const handleGetCommandClick = (inputCommand: string) => {
114 | const gitCommand = getGitCommand(inputCommand.toLowerCase())
115 | if (!gitCommand) {
116 | setIsInvalid(true)
117 | setMatchingCommand({} as GitCommand)
118 | } else {
119 | setIsInvalid(false)
120 | setMatchingCommand(gitCommand)
121 | }
122 | }
123 |
124 | return (
125 | git {command.name}
101 |{command.description}
102 | {flagsDescriptions &&Flags
} 103 | {flagsDescriptions && flagsDescriptions} 104 |
126 |
127 |
132 |
155 | )
156 | }
157 |
158 | export default App
159 |
--------------------------------------------------------------------------------
/src/git-command-parsing.tsx:
--------------------------------------------------------------------------------
1 | import { snakeToCamel } from './utils'
2 | import {
3 | AvailableFlagsArray,
4 | Flag,
5 | GitCommand,
6 | GitDefinition,
7 | ParsedArguments,
8 | SpecialTokens,
9 | } from './types'
10 | import Definition from './components/Definition'
11 | import { joinWithFinalAnd } from './utils'
12 |
13 | function getAvailableFlagsAsArray(availableFlagsObject: Flag[]): AvailableFlagsArray {
14 | const booleanFlagsArray = availableFlagsObject.reduce((acc, flag) => {
15 | if (!flag.isString) {
16 | if (flag.aliases) {
17 | return [...acc, flag.name, ...flag.aliases]
18 | }
19 |
20 | return [...acc, flag.name]
21 | }
22 |
23 | return acc
24 | }, [] as string[])
25 |
26 | const stringFlagsArray = availableFlagsObject.reduce((acc, flag) => {
27 | if (flag.isString) {
28 | if (flag.aliases) {
29 | return [...acc, flag.name, ...flag.aliases]
30 | }
31 |
32 | return [...acc, flag.name]
33 | }
34 |
35 | return acc
36 | }, [] as string[])
37 |
38 | return { booleanFlagsArray, stringFlagsArray }
39 | }
40 |
41 | function getMatchingFlags(availableFlags: Flag[], parsedArguments: ParsedArguments) {
42 | const matchingFlags = parsedArguments.flags.flatMap((inputFlag) => {
43 | // Filters out the boolean flags based on :
44 | // If the flag exists
45 | // If it's not _ (minimist prefix to store everything that's not a flag)
46 | // If the flag is either stored as its full name or the alias (only checks for aliases if the property exists)
47 | // TODO: add a check for duplicate
48 | return availableFlags.filter((availableFlag) => availableFlag.name === inputFlag.name)
49 | })
50 |
51 | return matchingFlags
52 | }
53 |
54 | // Parse the flags descriptions if needed
55 | // TODO: So far if a command has two times the same string value, it just joins them with a space. Needs to be improved for specific flags such as -m writing the message on two paragraphs.
56 | function getParsedFlagsDescriptions(flagsDescriptions: Flag[], commandArguments: ParsedArguments) {
57 | return flagsDescriptions.map((flag) => {
58 | if (flag.isString) {
59 | // Gets the matching string value for the current flag
60 | let stringFlagValue = commandArguments.flags.find((inputFlag) => inputFlag.name === flag.name)
61 | ?.value
62 | if (Array.isArray(stringFlagValue)) {
63 | stringFlagValue = stringFlagValue.join(' ')
64 | }
65 |
66 | if (typeof stringFlagValue === 'string') {
67 | return {
68 | ...flag,
69 | description: flag.description.replace('%s', stringFlagValue),
70 | }
71 | }
72 | }
73 | return flag
74 | })
75 | }
76 |
77 | function getAliasesAsObject(availableFlags: Flag[]) {
78 | return availableFlags.reduce((flagsList, flag) => {
79 | if (flag.aliases) {
80 | flagsList[snakeToCamel(flag.name)] = flag.aliases
81 | }
82 | return flagsList
83 | }, {} as any)
84 | }
85 |
86 | function replaceSpecialTokens(parsedArguments: ParsedArguments, specialTokens: SpecialTokens) {
87 | const updatedArguments = parsedArguments._.slice(2).map((argument) => {
88 | return (
89 | Object.entries(specialTokens).find(([tokenKey]) => tokenKey === argument)?.[1] ?? argument
90 | )
91 | })
92 |
93 | return { ...parsedArguments, _: updatedArguments }
94 | }
95 |
96 | // Transform a description string into an array of strings and Definition components based on the term is a git definition or not.
97 | function parseDescriptionWithGitDefinitions(
98 | text: string | (string | JSX.Element)[],
99 | definition: GitDefinition
100 | ) {
101 | let updatedDescription
102 | // This conditional is here because text can be either a string or an array, and it needs to be handled accordingly.
103 | if (typeof text === 'string') {
104 | updatedDescription = text.split(definition.regex).map((str) => {
105 | if (definition.regex.test(str)) {
106 | return 128 | >what the git 129 |
130 |enter a git command and have it explained to you
131 |
133 | setInputCommand(e.target.value)}
140 | onKeyDown={(e) => {
141 | if (e.code === 'Enter') {
142 | handleGetCommandClick(inputCommand)
143 | }
144 | }}
145 | />
146 |
149 | {isInvalid && (
150 |
154 |