Comments (3)
Very good question. It wonder if we can do something clever here that fixes two problems:
- These are text docs / markdown and so easy to get out of sync with our code or best practices. We don't break APIs very often -- but we will in a SHA256 compatible world. 😱
- Our "examples" are a poor attempt at a git cli implementation.
I can imagine a world where our examples are smaller pieces of code -- or that we pull the samples data out of the examples code itself. We probably wouldn't want all the boilerplate, so you can imagine something like:
#include "git2.h"
int main(int argc, char **argv)
{
/** sample start: clone (progress) */
progress_data d = {0};
git_clone_options clone_opts = GIT_CLONE_OPTIONS_INIT;
clone_opts.checkout_opts.checkout_strategy = GIT_CHECKOUT_SAFE;
clone_opts.checkout_opts.progress_cb = checkout_progress;
clone_opts.checkout_opts.progress_payload = &d;
clone_opts.fetch_opts.callbacks.transfer_progress = fetch_progress;
clone_opts.fetch_opts.callbacks.payload = &d;
git_repository *repo = NULL;
int error = git_clone(&repo, url, path, &clone_opts);
/** sample end */
}
from libgit2.github.io.
If all the example were easily compilable (modulo a bit of boiler plate) it would be pretty easy to programmatically check that deprecated symbols are removed.
It would be sufficient to #define GIT_DEPRECATE_HARD
and have them all compiled in the testing pipeline.
I believe there is some ad-hoc literate programming stuff that want to emerge from this problem 😛.
I may look into it later this week if I have some time.
from libgit2.github.io.
I had time earlier than expected, so I tinkered yesterday with a bit of python, and I think I am on the right track. Currently, I have a script that cut the existing index into independent files, and another one that seem back the files into a single markdown file. A third script converts the individual markdown files into C files and try to compile them.
The current state of the examples doesn't make this approach viable yet because it is basically impossible to parse a C snippet where the main function is implicit, but with some well-placed markings there should be no problem.
As an example, one file may be something like that:
One can track the progress of the clone operation thanks to a callback.
~~~c
typedef struct { /* … */ } progress_data;
int fetch_progress(
const git_indexer_progress *stats,
void *payload)
{
progress_data *pd = (progress_data*)payload;
/* Do something with network transfer progress */
}
void checkout_progress(
const char *path,
size_t cur,
size_t tot,
void *payload)
{
progress_data *pd = (progress_data*)payload;
/* Do something with checkout progress */
}
// !BEGIN_MAIN
progress_data d = {0};
git_clone_options clone_opts = GIT_CLONE_OPTIONS_INIT;
char *url = "https://github.com/libgit2/libgit2";
char *path = "libgit2";
clone_opts.checkout_opts.checkout_strategy = GIT_CHECKOUT_SAFE;
clone_opts.checkout_opts.progress_cb = checkout_progress;
clone_opts.checkout_opts.progress_payload = &d;
clone_opts.fetch_opts.callbacks.transfer_progress = fetch_progress;
clone_opts.fetch_opts.callbacks.payload = &d;
git_repository *repo = NULL;
int error = git_clone(&repo, url, path, &clone_opts);
~~~
([`git_clone`](http://libgit2.org/libgit2/#HEAD/group/clone/git_clone),
[`git_clone_options`](http://libgit2.org/libgit2/#HEAD/type/git_clone_options))
Which would either be pasted mostly as-is in the index.md
(without the !BEGIN_MAIN
mark, or maybe replacing it with a more human friendly comment) and would produce a C program like that:
/*
* Repositories
* Clone (Progress)
* This file is automatically generated for testing purpose.
*/
#define GIT_DEPRECATE_HARD
#include <git2.h>
/* One can track the progress of the clone operation thanks to a callback. */
typedef struct { /* … */ } progress_data;
int fetch_progress(
const git_indexer_progress *stats,
void *payload)
{
progress_data *pd = (progress_data*)payload;
/* Do something with network transfer progress */
}
void checkout_progress(
const char *path,
size_t cur,
size_t tot,
void *payload)
{
progress_data *pd = (progress_data*)payload;
/* Do something with checkout progress */
}
int main()
{
git_libgit2_init();
progress_data d = {0};
git_clone_options clone_opts = GIT_CLONE_OPTIONS_INIT;
char *url = "https://github.com/libgit2/libgit2";
char *path = "libgit2";
clone_opts.checkout_opts.checkout_strategy = GIT_CHECKOUT_SAFE;
clone_opts.checkout_opts.progress_cb = checkout_progress;
clone_opts.checkout_opts.progress_payload = &d;
clone_opts.fetch_opts.callbacks.transfer_progress = fetch_progress;
clone_opts.fetch_opts.callbacks.payload = &d;
git_repository *repo = NULL;
int error = git_clone(&repo, url, path, &clone_opts);
return 0;
}
/*
* ([`git_clone`](http://libgit2.org/libgit2/#HEAD/group/clone/git_clone),
* [`git_clone_options`](http://libgit2.org/libgit2/#HEAD/type/git_clone_options))
*/
Do you think this would be an acceptable solution for this project?
If so, would you be OK with python scripts? Alternatively, I can port them to ruby since Jekyll already require that.
from libgit2.github.io.
Related Issues (20)
- libqgit2 link broken? HOT 3
- Change libgit2.github.com to libgit2.github.io or libgit2.org HOT 2
- https://libgit2.org/libgit2 404 Not Found HOT 1
- AndroidStudio 'define inline' problem HOT 1
- First git_rebase_next fails in the presence of submodule changes. HOT 1
- libqgit2 link no longer works HOT 2
- Migrate site from redcarpet to kramdown
- git_submodule_lookup is O(N) w.r.t. number of submodules HOT 1
- is this really MIT? HOT 2
- git_status_list_new stopped creating status HOT 1
- Annotated Examples proposal
- change php-git link HOT 1
- Crash on running UnitTest with git2-15e1193.DLL with Studio vstest.executionengine.exe on Windows Server 2016 HOT 6
- Can't open libgit2 API Reference HOT 4
- Create push Refspec from a remote branch HOT 1
- broken link in Callbacks sample section HOT 1
- Security Information on the website looks outdated HOT 1
- Callbacks sample uses old git_transfer_progress
- How to use Git LFS with libgit2?
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from libgit2.github.io.