Difference between revisions of "Iegitaddmd"

Jump to: navigation, search
Line 1: Line 1:
Empty folders are ignored by GitHub and therefore not shared across project teams, but in research we often want to share template folder structures for new projects where some folders might be empty. '''iegitaddmd''' is used to create placeholder files in empty folders so that template project folder structures can be shared on GitHub even if some folders are note yet populated with project files.
Empty folders are ignored by GitHub and therefore not shared across project teams, but in research we often want to share template folder structures for new projects where some folders might be empty. '''iegitaddmd''' is used to create placeholder files in empty folders so that template project folder structures can be shared on GitHub even if some folders are note yet populated with project files.


This article is means to describe use cases, work flow and the reasoning used when developing the commands. For instructions on how to use the command specifically in Stata and for a complete list of the options available, see the help files by typing <code>help iegitaddmd</code> in Stata.
This article is means to describe use cases, work flow and the reasoning used when developing the commands. For instructions on how to use the command specifically in Stata and for a complete list of the options available, see the help files by typing <code>help iegitaddmd</code> in Stata. This command is a part of the package [[Stata_Coding_Practices#ietoolkit|ietoolkit]], to install all the commands in this package including this command, type <code>ssc install ietoolkit</code> in Stata.


== Intended use cases ==
== Intended use cases ==

Revision as of 13:53, 11 January 2018

Empty folders are ignored by GitHub and therefore not shared across project teams, but in research we often want to share template folder structures for new projects where some folders might be empty. iegitaddmd is used to create placeholder files in empty folders so that template project folder structures can be shared on GitHub even if some folders are note yet populated with project files.

This article is means to describe use cases, work flow and the reasoning used when developing the commands. For instructions on how to use the command specifically in Stata and for a complete list of the options available, see the help files by typing help iegitaddmd in Stata. This command is a part of the package ietoolkit, to install all the commands in this package including this command, type ssc install ietoolkit in Stata.

Intended use cases

It is common and highly recommended to use folder templates for new projects. Many organizations has folder structures templates and at DIME we have developed a command that set ups the folder structure for a new project with just one line of code. See iefolder. iefolder can also add more folder to a project folder that was initially set up with iefolder. For example, if you want to add an endline folder with sub-folders to a project folder that had only a baseline folder before.

When folder templates are used to create a project folder or add a survey round folder it is common that empty folders are created. For example, templates often include a Output folder where analysis output will be stored, but that folder will remain empty while the data set is cleaned and prepared for analysis. Let's say two people, person A and person B collaborate on a project using GitHub, and person B used a template like iefolder to create the project folder. If person A would do the first to do the analysis then there would be no Output folder for person A to store the outputs. Person A could of course create an output folder and call it anything, but that would defy the whole purpose of using a template in the first place.

iegitaddmd provides a solution to this. It creates a placeholder file in any empty folder called README.md in the project folder specified. Then these folders can be included in a commit on GitHub. You may remove these files as soon as these fodlers are populated with project files, but a better practice might be to update the text to describe and document the files in that folder.

Instead of the README.md file iegitaddmd produces you can specify a file saved to your computer that you want to use as placeholder file. It is strongly recommended that you use a raw text file format for this file, such as .md, .txt etc. Any code file like .do, .sthlp, .R, .py etc. are also raw text formats. If the format is .md and the file is named README (like the default file created) then the content is displayed in the browser when someone browses to that folder on github.com.

Intended Work Flow

Describe work flow here (remove if obvious from use case)

Instructions

These instructions are meant to help you understand how to use the command. For technical instructions on how to implement the command in Stata see the help files by typing help iegitaddmd in Stata.

Describe best practices related to this command here.

Reasoning used during development

Describe any non obvious decisions made during development of this command. This can help explain restrictions and requirements

Back to Parent

This article is part of the topic ietoolkit