---
title: "Introduction"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---




## Basic idea

Based on the definition proposed by [freecodecamp](https://www.freecodecamp.org/news/gitignore-what-is-it-and-how-to-add-to-repo/):

> The .gitignore file is a text file that tells Git which files or folders to ignore in a project. A local .gitignore file is usually placed in the root directory of a project. You can also create a global .gitignore file and any entries in that file will be ignored in all of your Git repositories.

For any project, it is therefore important to have a `.gitignore` file that is complete and accurate. The package `gitignore` provides a simple R interface to the [gitignore.io](https://www.toptal.com/developers/gitignore) API. It can be used to fetch gitignore templates that can be included into the `.gitignore` file of you git repository. The `gitignore` R package can be used with R package, R Studio project or with any `.gitignore` file. Note that by default, the `usethis` package populates the `.gitignore` for the R language when you create a R project. However, it is common to use many different programming languages in a project such as `LaTeX`, `python`, `matlab`, `julia` and so on. This is where the `gitignore` package shines as it can be used to programmatically modify the `.gitignore` file of your project.

`gitignore` is a simple R package that provide an interface to query [gitignore.io](https://www.toptal.com/developers/gitignore) to fetch gitignore templates that can be included in the .gitignore file. More than 450 templates are currently available. There are actually two functions in the package:

- `gi_available_templates()`: to get a list of all templates available on [gitignore.io](https://www.toptal.com/developers/gitignore).
- `gi_fetch_templates()`: to get one or more template(s). This function can copy the returned template(s) in the clipboard as well as happening the the `.gitignore` file in your project directory.

## Examples


```r
library(gitignore)
```

Get the list of all available templates from [gitignore.io](https://www.toptal.com/developers/gitignore):


```r
head(gi_available_templates(), 50)
#>  [1] "1c"                   "1c-bitrix"           
#>  [3] "a-frame"              "actionscript"        
#>  [5] "ada"                  "adobe"               
#>  [7] "advancedinstaller"    "adventuregamestudio" 
#>  [9] "agda"                 "al"                  
#> [11] "alteraquartusii"      "altium"              
#> [13] "amplify"              "android"             
#> [15] "androidstudio"        "angular"             
#> [17] "anjuta"               "ansible"             
#> [19] "ansibletower"         "apachecordova"       
#> [21] "apachehadoop"         "appbuilder"          
#> [23] "appceleratortitanium" "appcode"             
#> [25] "appcode+all"          "appcode+iml"         
#> [27] "appengine"            "aptanastudio"        
#> [29] "arcanist"             "archive"             
#> [31] "archives"             "archlinuxpackages"   
#> [33] "asdf"                 "aspnetcore"          
#> [35] "assembler"            "astro"               
#> [37] "ate"                  "atmelstudio"         
#> [39] "ats"                  "audio"               
#> [41] "autohotkey"           "automationstudio"    
#> [43] "autotools"            "autotools+strict"    
#> [45] "awr"                  "azurefunctions"      
#> [47] "azurite"              "backup"              
#> [49] "ballerina"            "basercms"
```

The function `gi_fetch_templates()` can be used to fetch particular template(s). For example, one could want to get the `java` and `c++` templates as follow:


```r
gi_fetch_templates(c("java", "c++"))
#> # Created by https://www.toptal.com/developers/gitignore/api/java,c++
#> # Edit at https://www.toptal.com/developers/gitignore?templates=java,c++
#> 
#> ### C++ ###
#> # Prerequisites
#> *.d
#> 
#> # Compiled Object files
#> *.slo
#> *.lo
#> *.o
#> *.obj
#> 
#> # Precompiled Headers
#> *.gch
#> *.pch
#> 
#> # Compiled Dynamic libraries
#> *.so
#> *.dylib
#> *.dll
#> 
#> # Fortran module files
#> *.mod
#> *.smod
#> 
#> # Compiled Static libraries
#> *.lai
#> *.la
#> *.a
#> *.lib
#> 
#> # Executables
#> *.exe
#> *.out
#> *.app
#> 
#> ### Java ###
#> # Compiled class file
#> *.class
#> 
#> # Log file
#> *.log
#> 
#> # BlueJ files
#> *.ctxt
#> 
#> # Mobile Tools for Java (J2ME)
#> .mtj.tmp/
#> 
#> # Package Files #
#> *.jar
#> *.war
#> *.nar
#> *.ear
#> *.zip
#> *.tar.gz
#> *.rar
#> 
#> # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
#> hs_err_pid*
#> replay_pid*
#> 
#> # End of https://www.toptal.com/developers/gitignore/api/java,c++
```

By default, the template(s) are not copied into the clipboard, this can be changed by setting `copy_to_clipboard = TRUE`:


```r
gi_fetch_templates(c("java", "c++"), copy_to_clipboard = TRUE)
```

Additionally, you can tell `gi_fetch_templates()` to append automatically the `.gitignore` file in your project by setting `append_gitignore = TRUE`:


```r
gi_fetch_templates(c("R"), append_gitignore = TRUE)
```

It is also possible to specify the `.gitignore` file to be modified by specifying the `gitignore_file` argument.


```r
f <- file.path(tempdir(), ".gitignore")

file.create(f)
#> [1] TRUE

gi_fetch_templates("R", gitignore_file = f, append_gitignore = TRUE)
#> # Created by https://www.toptal.com/developers/gitignore/api/r
#> # Edit at https://www.toptal.com/developers/gitignore?templates=r
#> 
#> ### R ###
#> # History files
#> .Rhistory
#> .Rapp.history
#> 
#> # Session Data files
#> .RData
#> .RDataTmp
#> 
#> # User-specific files
#> .Ruserdata
#> 
#> # Example code in package build process
#> *-Ex.R
#> 
#> # Output files from R CMD build
#> /*.tar.gz
#> 
#> # Output files from R CMD check
#> /*.Rcheck/
#> 
#> # RStudio files
#> .Rproj.user/
#> 
#> # produced vignettes
#> vignettes/*.html
#> vignettes/*.pdf
#> 
#> # OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
#> .httr-oauth
#> 
#> # knitr and R markdown default cache directories
#> *_cache/
#> /cache/
#> 
#> # Temporary files created by R markdown
#> *.utf8.md
#> *.knit.md
#> 
#> # R Environment Variables
#> .Renviron
#> 
#> # pkgdown site
#> docs/
#> 
#> # translation temp files
#> po/*~
#> 
#> # RStudio Connect folder
#> rsconnect/
#> 
#> ### R.Bookdown Stack ###
#> # R package: bookdown caching files
#> /*_files/
#> 
#> # End of https://www.toptal.com/developers/gitignore/api/r
#> ● .gitignore file successfully modified.

readLines(f)
#>  [1] "# Created by https://www.toptal.com/developers/gitignore/api/r"      
#>  [2] "# Edit at https://www.toptal.com/developers/gitignore?templates=r"   
#>  [3] ""                                                                    
#>  [4] "### R ###"                                                           
#>  [5] "# History files"                                                     
#>  [6] ".Rhistory"                                                           
#>  [7] ".Rapp.history"                                                       
#>  [8] "# Session Data files"                                                
#>  [9] ".RData"                                                              
#> [10] ".RDataTmp"                                                           
#> [11] "# User-specific files"                                               
#> [12] ".Ruserdata"                                                          
#> [13] "# Example code in package build process"                             
#> [14] "*-Ex.R"                                                              
#> [15] "# Output files from R CMD build"                                     
#> [16] "/*.tar.gz"                                                           
#> [17] "# Output files from R CMD check"                                     
#> [18] "/*.Rcheck/"                                                          
#> [19] "# RStudio files"                                                     
#> [20] ".Rproj.user/"                                                        
#> [21] "# produced vignettes"                                                
#> [22] "vignettes/*.html"                                                    
#> [23] "vignettes/*.pdf"                                                     
#> [24] "# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3"
#> [25] ".httr-oauth"                                                         
#> [26] "# knitr and R markdown default cache directories"                    
#> [27] "*_cache/"                                                            
#> [28] "/cache/"                                                             
#> [29] "# Temporary files created by R markdown"                             
#> [30] "*.utf8.md"                                                           
#> [31] "*.knit.md"                                                           
#> [32] "# R Environment Variables"                                           
#> [33] ".Renviron"                                                           
#> [34] "# pkgdown site"                                                      
#> [35] "docs/"                                                               
#> [36] "# translation temp files"                                            
#> [37] "po/*~"                                                               
#> [38] "# RStudio Connect folder"                                            
#> [39] "rsconnect/"                                                          
#> [40] "### R.Bookdown Stack ###"                                            
#> [41] "# R package: bookdown caching files"                                 
#> [42] "/*_files/"                                                           
#> [43] "# End of https://www.toptal.com/developers/gitignore/api/r"
```

