Skip to content

Commit 022f559

Browse files
authored
Merge pull request #1350 from mohseenrm/nodegit-docs
Adding docs for NodeGit
2 parents c2fac2f + 0e2dffa commit 022f559

File tree

8 files changed

+106
-0
lines changed

8 files changed

+106
-0
lines changed

examples/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
## /examples
2+
3+
List of examples of using NodeGit to implement common git core operations.
4+

generate/README.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## /generate
2+
3+
The scripts and templates in this dir help generate the source code and tests for NodeGit. The major components of generate are:
4+
5+
1. Input
6+
2. Scripts
7+
3. Templates
8+
9+
### Input
10+
11+
All the **configuration** required for the parser to generate the source code and tests. For more details, check the Input directory.
12+
13+
### Scripts
14+
15+
The scripts that generate the final configuration (*snapshot of the library*) `idefs.json`, `missing-tests.json`. These configurations are then used to generate `src` for the library.
16+
17+
### Templates
18+
19+
All the Combyne templates are placed here. The filters, partials, templates all help NodeGit generate the source code.
20+
21+
> For more information on Combyne: [tbranyen/combyne](https://github.com/tbranyen/combyne)

generate/input/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
## /generate/input
2+
This folder contains the main config files to generate NodeGit
3+
4+
#### Callbacks
5+
Add all meta data about the callbacks from libgit2 that need to be implemented in NodeGit
6+
7+
#### Descriptor
8+
Customize the generated code using this configuration. Enter the function signature, arguments and their metadata and which functions can be skipped in this file. If you're using a manual template, remove all its references from this file.
9+
10+
#### Libgit2-docs
11+
These are provided by the libgit2 team. Includes all metadata about the api provided by the libgit2 library.
12+
13+
#### Libgit2-supplement
14+
Use this confiuration file to group and override parts of the generated code. NodeGit tries it's best to generate the right classes and structs, if that is not the case, use this config file to group/remove the functions.
15+
> If you're using manual templates, update the `cFile` reference to point to the manual template

generate/templates/README.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Manual templates
2+
3+
Manual templates override generated code from nodegit while generating source code. They really should be avoid untill absolutely necessary.
4+
5+
## Why?
6+
7+
#### 1. Performance
8+
> Everytime the library switches between C land and the javascript thread, there is a penalty in performance. If in practice the usage of a method in libgit2 requires crossing the c/javascript boundary frequently, it might be better option to use manual templates. An example being ```Revwalk::FastWalk```.
9+
10+
#### 2. Saftey
11+
> The generated code sometimes does not handle structures that are interdependent. An example would be ```git_patch``` and ```git_diff```. A ```git_patch```'s memory is owned by ```git_diff```, and that includes all of the children of ```git_patch```, as well. So a ```git_diff_hunk```, ```git_diff_line```, and ```git_patch``` all are owned by a ```git_diff```, and when that ```git_diff``` is deleted, all the memory for any patches, hunks, or lines that are in use as NodeGitWrappers are now corrupted. Further, a ```git_diff``` keeps a file handle open for its entire lifespan, which can lead to NodeGit holding onto file locks in Windows. Due to both of these compounding issues, we wrote manual templates to shift ownership away from a ```git_diff``` to ```git_patch```, ```git_diff_hunk```, and ```git_diff_line``` and also shorten the lifespan of a diff.
12+
13+
#### 3. Odd cases
14+
> If a new pattern exists in libgit that would be difficult to implement using generated code, manual templates can be used for one-off cases. Typically generated code takes care of most patterns seen in libgit, but if function signatures do not follow typical pattern, manual templates could be used. Example: ```git_filter``` and ```git_remote_ls```.
15+
16+
<br />
17+
-----
18+
## Implementing manual templates
19+
20+
#### 1. Write manual .cc and .h files to *generate/templates/manual/*
21+
*.cc files -> /generate/templates/manual/src/
22+
*.h files -> /generate/templates/manual/include/
23+
24+
#### 2. Remove all references from /generate configuration files
25+
26+
#### 3. Add references to binding.gyp template
27+
location: /generate/templates/templates/binding.gyp
28+
29+
#### 4. Add headers to nodegit.cc template
30+
location: /generate/templates/templates/nodegit.cc
31+
32+
#### 5. Add new wrapper to nodegit.js template
33+
use rawApi.ManualWrapper reference to add _ManualWrapper
34+
add any js wrapper (if any) via importExtension
35+

lib/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## /lib
2+
3+
Contains javascript extensions for the generated NodeGit modules. Any additional behavior on top of the standard libgit2 behavior will be found here.

lifecycleScripts/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## /lifecycleScripts
2+
3+
These scripts are responsible for downloading the right dependencies, configuring vendors, and all other dependencies that are required to build, generate, and clean the module.
4+
5+

test/README.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## /test
2+
3+
Contains all the test scripts, runner, and keys for running the tests.
4+
5+
-----------
6+
7+
#### /home
8+
Contains gitconfig for the test repositories.
9+
10+
#### /repos
11+
Contains blame, empty, nonrepo, and workdir test repositories.
12+
13+
#### /tests
14+
Unit tests for NodeGit.
15+
16+
#### /utils
17+
Test utilities with garbage collector, index, and repository setup, that can be used in tests.

utils/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## /utils
2+
3+
Contains utilities for NodeGit
4+
5+
#### buildFlags
6+
Determines how NodeGit should build. Use `BUILD_ONLY` environment variable to build from source.

0 commit comments

Comments
 (0)