Difference between revisions 705257 and 706892 on mediawikiwiki

< previous diff
next diff >
Template:Gerrit file/doc
<noinclude>{{Documentation subpage}}
{{timw|{{BASEPAGENAME}}}}
</noinclude>
<!-- PUT HERE THE DOCUMENTATION -->
This generates a link to a file on [[Gerrit]].

The goal is to avoid ugly URLs in wiki text like
  https://gerrit.wikimedia.org/r/gitweb?p=blob/mediawiki/%2Fextensions/%2Fexamples.git;f=/HEAD/BoilerPlate/%2FREADME;hb=HEAD
and also future-proof (ha ha) these links against changes and evolution to source code control, such as swapping gitweb for GitBlit ({{bug|38383}}).

== Usage ==
; basic
 <nowiki>{{git file</nowiki> |project=mediawiki/extensions/''examples'' |file=''BoilerPlate/README'' }}
produces
:{{git file|project=mediawiki/extensions/examples|file=BoilerPlate/README }}

; action
 <nowiki>{{git file</nowiki> |project=mediawiki/extensions/ArticleFeedback 
 |file=modules/jquery.articleFeedback/images/star-new-down.png
 |text=star image | action=blob_plain }}
produces
:{{git file|project=mediawiki/extensions/ArticleFeedback 
 |file=modules/jquery.articleFeedback/images/star-new-down.png
 |text=star image |action=blob_plain}}

; link to line number, default project
 <nowiki>{{git file |file=tests/phpunit/includes/IPTest.php |line=123 }}</nowiki>
produces
:{{git file |file=tests/phpunit/includes/IPTest.php |line=123 }}

; a project (no filename, so use text)
 <nowiki>{{git file</nowiki> |project=mediawiki/extensions/agora
 |text=Agora extension}}
produces
:{{git file |project=mediawiki/extensions/Agora |text=Agora extension}}

=== Parameters ===
; project
: defaults to mediawiki/core. Must be entire path to project &mdash; usually mediawiki/ , often followed by extensions/, then your project &mdash; but not the <tt>.git</tt> suffix.
; file
: optional. A file or directory within the project, without the leading ''''/'''<nowiki>'</nowiki>.  If you just want to link to the project, use {{tl|gitweb}}. Note to avoid confusion you may want to invoke this template with underscore &mdash; <code><nowiki>{{git</nowiki>'''_'''file | file=''name''}}</code>.
; text
: optional. The text that's linked.  If not specified, defaults to file.
; action
: optional. You can give a gerrit action, e.g. <code>action=blob_raw</code> , <code>action=tree</code> (gerrit/gitweb infers this if file= a directory)... ''TODO: what are the other values?''
; line
: optional. <code>line=42</code> will add a fragment to the URL that positions the browser at line 42 of the file.

== Issues ==
* action= is gerrit-specific, maybe abstract away from gerrit to format=raw/''mimetype''/...
* TODO: add branch= parameter
* ? Merge with {{tl|Git}}, or maybe {{tl|Gerrit}}, {{tl|MW file}}, etc. but simpler?

== Notes ==
The template has to use numeric entities <code>&amp;#59;</code> and <code>&amp;32;</code> for semicolon and hashmark because as [[w:Wikipedia:Advanced_template_coding#MediaWiki_wiki-formats_the_clauses_inside_.23if|WP:Advanced template coding]] says "MediaWiki wiki-formats the clauses inside #if".
MW would sometimes parse these characters as introducing a definition term and numbered list (even though t they're not at the start of new lines!).

== See also ==
* this replaces Template:GitwebFile that had almost exactly the same functionality (but undocumented and uncategorized so spage missed it)
* {{tl|MW file}} generates complicated link to file, used by [[Manual]]
* lots of other fancy templates for extensions on gerrit, see [[:Category:Git]]
<includeonly>
<!-- PUT HERE THE CATEGORIES OF THE TEMPLATE -->
[[Category:Git| ]]
</includeonly>