wpide / git / README.md

README.md in WPIDE – File Manager & Code Editor 2.3.2, at git/README.md

188 lines 8.6 KB

Raw Download Zip

1	Git Streamwrapper for PHP
2	=========================
3
4	[](http://travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git![Build Status](https://secure.travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git.png)](http://travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git](http://travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git)
5
6	Git Streamwrapper for PHP is a PHP library that allows PHP code to interact with one or multiple Git repositories from within an application. The library consists of a Git repository abstraction that can be used to programatically access Git repositories and of a stream wrapper that can be hooked into the PHP stream infrastructure to allow the developer to use file and directory access functions directly on files in a Git repository. The library provides means to access status information on a Git repository, such as the log, the current repository status or commit information, as well.
7
8	The Git Streamwrapper for PHP core is a wrapper around the Git command line binary so it is required to have Git installed on the machine running the PHP code. **Git Streamwrapper for PHP does not include a Git protocol abstraction**, it relies on the Git command line binary for all its functionality.
9
10	The code is currently running stable (see comments on Windows below) and should be API-stable. It's however not feature-complete - so please feel free to request features you require.
11
12
13	Examples
14	--------
15
16	### Using the repository abstraction
17
18	```php
19	use TQ\Git\Cli\Binary;
20	use TQ\Git\Repository\Repository;
21	// open an already initialized repository
22	$git = Repository::open('/path/to/your/repository', new Binary('/usr/bin/git'));
23
24	// open repository and create path and init repository if necessary
25	$git = Repository::open('/path/to/your/repository', new Binary('/usr/bin/git'), 0755);
26
27	// get current branch
28	$branch = $git->getCurrentBranch();
29
30	// get status of working directory
31	$status = $git->getStatus();
32	// are there uncommitted changes in the staging area or in the working directory
33	$isDirty = $git->isDirty();
34
35	// retrieve the commit log limited to $limit entries skipping the first $skip
36	$log = $git->getLog($limit, $skip);
37
38	// retrieve the second to last commit
39	$commit = $git->showCommit('HEAD^');
40
41	// list the directory contents two commits before
42	$list = $git->listDirectory('.', 'HEAD^^');
43
44	// show contents of file $file at commit abcd123...
45	$contents = $git->showFile($file, 'abcd123');
46
47	// write a file and commit the changes
48	$commit = $git->writeFile('test.txt', 'Test', 'Added test.txt');
49
50	// remove multiple files
51	$commit = $git->removeFile('file_*', 'Removed all files not needed any more');
52
53	// rename a file
54	$commit = $c->renameFile('test.txt', 'test.txt-old', 'Made a backup copy');
55
56	// do some file operations and commit all changes at once
57	$result = $git->transactional(function(TQ\Git\Repository\Transaction $t) {
58	file_put_contents($t->getRepositoryPath().'/text1.txt', 'Test 1');
59	file_put_contents($t->getRepositoryPath().'/text2.txt', 'Test 2');
60
61	unlink($t->resolvePath('old.txt'));
62	rename($t->resolvePath('to_keep.txt'), $t->resolvePath('test3.txt'));
63
64	$t->setCommitMsg('Don\'t know what to write here');
65
66	// if we throw an execption from within the callback the changes are discarded
67	// throw new Exception('No we don\'t want to to these changes');
68	// note: the exception will be re-thrown by the repository so you have to catch
69	// the exception yourself outside the transactional scope.
70	});
71	```
72
73	### Using the streamwrapper
74
75	```php
76	use TQ\Git\Cli\Binary;
77	use TQ\Git\StreamWrapper\StreamWrapper;
78
79	// register the wrapper
80	StreamWrapper::register('git', new Binary('/usr/bin/git'));
81
82	// read the contents of a file
83	$content = file_get_contents('git:///path/to/your/repository/file_0.txt');
84
85	// show contents of a file at commit abcd123...
86	$content = file_get_contents('git:///path/to/your/repository/file_0.txt#abcd123');
87
88	// show contents of a file two commits before
89	$content = file_get_contents('git:///path/to/your/repository/file_0.txt#HEAD^^');
90
91	// show the directory information two commits before
92	$directory = file_get_contents('git:///path/to/your/repository/#HEAD^^');
93
94	// list directory contents two commits before
95	$dir = opendir('git:///path/to/your/repository/subdir#HEAD^^');
96	while ($f = readdir($dir)) {
97	echo $f.PHP_EOL;
98	}
99	closedir($dir);
100
101	// recursively traverse the repository two commits before
102	$dir = new RecursiveDirectoryIterator('git:///path/to/your/repository#HEAD^^');
103	$it = new RecursiveIteratorIterator($dir, RecursiveIteratorIterator::SELF_FIRST);
104	foreach ($it as $fileInfo) {
105	echo str_repeat(' ', $it->getDepth() * 3).$fileInfo->getFilename().PHP_EOL;
106	}
107
108	// retrieve the second to last commit
109	$commit = file_get_contents('git:///path/to/your/repository?commit&ref=HEAD^^');
110
111	// retrieve the commit log limited to 5entries skipping the first 2
112	$log = file_get_contents('git:///path/to/your/repository?log&limit=5&skip=2');
113
114	// remove a file - change is committed to the repository
115	unlink('git:///path/to/your/repository/file_to_delete.txt');
116
117	// rename a file - change is committed to the repository
118	rename('git:///path/to/your/repository/old.txt', 'git:///path/to/your/repository/new.txt');
119
120	// remove a directory - change is committed to the repository
121	rmdir('git:///path/to/your/repository/directory_to_delete');
122
123	// create a directory - change is committed to the repository
124	// this creates a .gitkeep file in new_directory because Git does not track directories
125	mkdir('git:///path/to/your/repository/new_directory');
126
127	// write to a file - change is committed to the repository when file is closed
128	$file = fopen('git:///path/to/your/repository/test.txt', 'w');
129	fwrite($file, 'Test');
130	fclose($file);
131
132	// support for stream context
133	$context = stream_context_create(array(
134	'git' => array(
135	'commitMsg' => 'Hello World',
136	'author' => 'Luke Skywalker <skywalker@deathstar.com>'
137	)
138	));
139	$file = fopen('git:///path/to/your/repository/test.txt', 'w', false, $context);
140	fwrite($file, 'Test');
141	fclose($file); // file gets committed with the preset commit message and author
142
143	// append to a file using file_put_contents using a custom author and commit message
144	$context = stream_context_create(array(
145	'git' => array(
146	'commitMsg' => 'Hello World',
147	'author' => 'Luke Skywalker <skywalker@deathstar.com>'
148	)
149	));
150	file_put_contents('git:///path/to/your/repository/test.txt', 'Test', FILE_APPEND, $context);
151
152	// unregister the wrapper if needed
153	StreamWrapper::unregister();
154	```
155
156	Requirements
157	------------
158
159	- PHP > 5.3.0
160	- Git installed on the machine running the PHP code
161
162	Run tests
163	---------
164
165	1. clone the repository
166	2. copy `phpunit.xml.dist` to `phpunit.xml`
167	3. adjust the `GIT_BINARY` constant in `phpunit.xml` to the path to your Git binary
168	4. run `phpunit` from within the cloned project folder
169
170	Please note that the library has been tested on a Mac OS X 10.7 with the bundled PHP 5.3.6 (git version 1.7.6), on several Ubuntu Linux installations and on Windows Vista running PHP 5.3.7 (1.7.6.msysgit.0). Due to currently unknown reasons the test run a bit unstable on Windows. All tests should be green but during cleanup there may be the possibility that some access restrictions randomly kick in and prevent the cleanup code from removing the test directories.
171
172	The unit test suite is continuously tested with [](http://travis-ci.org/Travis CI](http://travis-ci.org/](http://travis-ci.org/) on PHP 5.3 and 5.4 and its current status is: [](http://travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git![Build Status](https://secure.travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git.png)](http://travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git](http://travis-ci.org/teqneers/PHP-Stream-Wrapper-for-Git)
173
174	Contribute
175	----------
176
177	Please feel free to use the Git issue tracking to report back any problems or errors. You're encouraged to clone the repository and send pull requests if you'd like to contribute actively in developing the library.
178
179	License
180	-------
181
182	Copyright (C) 2011 by TEQneers GmbH & Co. KG
183
184	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:
185
186	The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
187
188	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.